@harapter/transport-acp 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,97 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-acp</code></h1>
+
+<p align="center"><strong>stable Agent Client Protocol v1 の strict Provider-neutral client。</strong></p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.ja.md">日本語</a> · <a href="../../README.ja.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/transport-acp"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-acp/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-acp"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-acp?style=flat-square" alt="npm ダウンロード数"></a>
+  <a href="https://github.com/yunfeizhu/harapter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/yunfeizhu/harapter/ci.yml?branch=main&amp;style=flat-square&amp;label=ci" alt="CI ステータス"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 24 以上">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0B7285?style=flat-square" alt="Apache-2.0 ライセンス"></a>
+  <img src="https://img.shields.io/badge/status-pre--alpha-EA580C?style=flat-square" alt="Pre-alpha ステータス">
+</p>
+
+<!-- markdownlint-enable MD033 -->
+
+`@harapter/transport-jsonrpc-stdio` を組み合わせ、stable ACP v1
+negotiation、Session method、Prompt、typed update、Permission
+Request、Capability Gate、未知 message の bounded observation を実装します。ACP
+Agent の起動、Provider 選択、Harapter Event mapping は行いません。
+
+## インストール
+
+```bash
+pnpm add @harapter/transport-acp@next
+```
+
+## クイックスタート
+
+```ts
+import { AcpClient } from '@harapter/transport-acp';
+
+const client = new AcpClient({
+  readable: controlledProcess.stdout,
+  writable: controlledProcess.stdin,
+  cleanup: () => stopControlledProcess(controlledProcess),
+  requestPermission: async (request) =>
+    decidePermissionWithoutLoggingRawFields(request),
+});
+
+await client.initialize({
+  clientInfo: { name: 'harapter-provider', version: 'current' },
+});
+
+const session = await client.newSession({
+  cwd: controlledWorkspace,
+  mcpServers: [],
+});
+
+const eventTask = (async () => {
+  for await (const event of client.events()) {
+    await handleValidatedAcpEvent(event);
+  }
+})();
+
+await client.prompt({
+  sessionId: session.sessionId,
+  prompt: [{ type: 'text', text: controlledPrompt }],
+});
+
+await client.close();
+await eventTask;
+```
+
+## 実装済み ACP v1 範囲
+
+- JSON-RPC `"2.0"` と `protocolVersion: 1` の厳密な negotiation；
+- `session/new` と Capability-gated load/list/delete/resume/close；
+- `session/prompt`、stable v1 `session/update`、`session/cancel`；
+- `session/request_permission` と `_` で始まる明示的 extension method；
+- 将来・未知 message の bounded redacted observation。
+
+ACP v2、authentication、logout、terminal、filesystem、elicitation、Session
+mode、Session configuration method は現在の stable profile 外です。未実装 Client
+Service を Capability として宣言することはできません。
+
+## ライフサイクル要点
+
+- connection ごとに initialize は一回、Session ごとに active Prompt は一つです；
+- 検証済み `session/prompt` response と stable stop
+  reason だけが終端 authority です；
+- `cancelSession()` の notification
+  write 成功だけでは cancellation を証明しません；
+- local
+  timeout/abort は cancel を送らず、未確認 Prompt は Session 再利用を止めます；
+- `events()` の consumer は一つで、既定の未読上限は 128 です；
+- 未知 message は success に変換されず、raw
+  observation の文字列や ID は hash または除去されます。
+
+Extension callback、Permission Payload、Tool Raw Input/Output、Remote
+Error は明示的 unredacted boundary です。全 protocol と race semantics は
+[英語の詳細ドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/transport-acp`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-acp</code></h1>
+
+<p align="center"><strong>A strict, Provider-neutral client for the stable Agent Client Protocol v1.</strong></p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.ja.md">日本語</a> · <a href="../../README.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/transport-acp"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-acp/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-acp"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-acp?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/yunfeizhu/harapter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/yunfeizhu/harapter/ci.yml?branch=main&amp;style=flat-square&amp;label=ci" alt="CI status"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 24 or newer">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0B7285?style=flat-square" alt="Apache-2.0 license"></a>
+  <img src="https://img.shields.io/badge/status-pre--alpha-EA580C?style=flat-square" alt="Pre-alpha status">
+</p>
+
+<!-- markdownlint-enable MD033 -->
 
 `@harapter/transport-acp` is Harapter's Provider-neutral client for the stable
 Agent Client Protocol v1 wire contract. It composes
@@ -12,6 +31,14 @@ portable Harapter lifecycle events, or infer capabilities from an Agent name.
 The consuming Provider Adapter owns process policy, Provider meaning, Session
 ownership, compatibility, and portable event and error mapping.
 
+## Use this package when
+
+- an Adapter connects to an Agent that implements stable ACP v1;
+- you need negotiated Session methods, typed updates, permission requests, and
+  bounded unknown-message observation; or
+- you want ACP validation without importing Provider identity or process policy
+  into a reusable transport layer.
+
 ## Installation
 
 ```bash
@@ -127,7 +154,7 @@ payloads, negotiated `_meta`, known tool `rawInput` and `rawOutput`, remote
 errors, and authentication-method values must not be logged or attached to
 portable errors without Adapter-owned validation and redaction.
 
-## Example
+## Quick start
 
 ```ts
 import { AcpClient } from '@harapter/transport-acp';

package/README.zh-CN.md

@@ -0,0 +1,94 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-acp</code></h1>
+
+<p align="center"><strong>严格、Provider 无关的稳定 Agent Client Protocol v1 客户端。</strong></p>
+
+<p align="center">
+  <a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.ja.md">日本語</a> · <a href="../../README.zh-CN.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/transport-acp"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-acp/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-acp"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-acp?style=flat-square" alt="npm 下载量"></a>
+  <a href="https://github.com/yunfeizhu/harapter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/yunfeizhu/harapter/ci.yml?branch=main&amp;style=flat-square&amp;label=ci" alt="CI 状态"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D24-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 24 或更高版本">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-0B7285?style=flat-square" alt="Apache-2.0 许可证"></a>
+  <img src="https://img.shields.io/badge/status-pre--alpha-EA580C?style=flat-square" alt="Pre-alpha 状态">
+</p>
+
+<!-- markdownlint-enable MD033 -->
+
+这个包组合 `@harapter/transport-jsonrpc-stdio`，实现稳定 ACP
+v1 的协商、Session 方法、Prompt、类型化更新、Permission Request、Capability
+Gate 和有界未知消息观测。它不启动 ACP Agent，也不选择 Provider 或把 ACP
+Event 映射成 Harapter Event。
+
+## 安装
+
+```bash
+pnpm add @harapter/transport-acp@next
+```
+
+## 快速开始
+
+```ts
+import { AcpClient } from '@harapter/transport-acp';
+
+const client = new AcpClient({
+  readable: controlledProcess.stdout,
+  writable: controlledProcess.stdin,
+  cleanup: () => stopControlledProcess(controlledProcess),
+  requestPermission: async (request) =>
+    decidePermissionWithoutLoggingRawFields(request),
+});
+
+await client.initialize({
+  clientInfo: { name: 'harapter-provider', version: 'current' },
+});
+
+const session = await client.newSession({
+  cwd: controlledWorkspace,
+  mcpServers: [],
+});
+
+const eventTask = (async () => {
+  for await (const event of client.events()) {
+    await handleValidatedAcpEvent(event);
+  }
+})();
+
+await client.prompt({
+  sessionId: session.sessionId,
+  prompt: [{ type: 'text', text: controlledPrompt }],
+});
+
+await client.close();
+await eventTask;
+```
+
+## 已实现的 ACP v1 范围
+
+- 精确 JSON-RPC `"2.0"` 和 `protocolVersion: 1` 协商；
+- `session/new`、按能力启用的 load/list/delete/resume/close；
+- `session/prompt`、稳定 v1 `session/update`、`session/cancel`；
+- `session/request_permission` 与 `_` 开头的显式扩展方法；
+- 未来或未知消息的有界、脱敏结构观测。
+
+ACP v2、认证、logout、terminal、filesystem、elicitation、Session mode 和 Session
+configuration 方法不在当前稳定 Profile 中。未实现的 Client
+Service 不能被伪装成已支持能力。
+
+## 生命周期要点
+
+- 一条连接只初始化一次，同一 Session 同时只有一个 Prompt；
+- 只有验证通过的 `session/prompt` 响应和稳定 stop reason 才是权威终态；
+- `cancelSession()` 会发送原生通知，但写入成功本身不是取消终态；
+- 本地 timeout/abort 不发送取消，未确认的远端 Prompt 会阻止 Session 复用；
+- `events()` 只有一个消费者，默认最多缓存 128 个未读事件；
+- 未知消息不会被猜测为成功，任意字符串和标识符会在 Raw
+  Observation 中被散列或移除。
+
+扩展回调、Permission Payload、Tool Raw Input/Output 和 Remote
+Error 是显式不脱敏边界，调用方必须自行执行数据策略。完整协议范围与竞态语义见
+[英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/transport-acp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Provider-neutral stable ACP v1 client for Harapter providers.",
   "keywords": [
     "agent",
@@ -17,11 +17,13 @@
   "bugs": {
     "url": "https://github.com/yunfeizhu/harapter/issues"
   },
-  "homepage": "https://github.com/yunfeizhu/harapter#readme",
+  "homepage": "https://github.com/yunfeizhu/harapter/tree/main/packages/transport-acp#readme",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "README.zh-CN.md",
+    "README.ja.md"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -41,7 +43,7 @@
     "tag": "next"
   },
   "dependencies": {
-    "@harapter/transport-jsonrpc-stdio": "0.1.1"
+    "@harapter/transport-jsonrpc-stdio": "0.1.2"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json"