@harapter/transport-jsonrpc-stdio 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,92 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-jsonrpc-stdio</code></h1>
+
+<p align="center"><strong>呼び出し側が所有する Node Stream 上の bounded bidirectional JSONL RPC。</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-jsonrpc-stdio"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-jsonrpc-stdio/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-jsonrpc-stdio"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-jsonrpc-stdio?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 -->
+
+stdin/stdout などの Node Stream で、一行一 JSON object の RPC を扱う Provider
+Adapter 向け transport です。framing、request
+correlation、順序付き inbound、backpressure、timeout、cleanup を担いますが、Provider
+method を解釈せず、Harapter の Session、Run、終端結果を生成しません。
+
+## インストール
+
+```bash
+pnpm add @harapter/transport-jsonrpc-stdio@next
+```
+
+## クイックスタート
+
+```ts
+import { JsonRpcStdioTransport } from '@harapter/transport-jsonrpc-stdio';
+
+const transport = new JsonRpcStdioTransport({
+  readable: controlledProcess.stdout,
+  writable: controlledProcess.stdin,
+  cleanup: () => stopControlledProcess(controlledProcess),
+});
+
+const incoming = (async () => {
+  for await (const message of transport.incoming()) {
+    await validateAndMapProviderMessage(message);
+  }
+})();
+
+const initialized = await transport.request('initialize', {
+  clientInfo: { name: 'harapter-provider', version: 'current' },
+});
+
+await validateInitializeResult(initialized);
+await transport.close();
+await incoming;
+```
+
+## よくある使い方
+
+- `request()` は対応する response を待ち、`notify()`
+  は notification だけを書きます；
+- `incoming()` の consumer は一つだけです；
+- 終端 response より前の Event 処理を待つ場合は `requestAfterInbound()`
+  を使います；
+- Provider 側で解決済みの remote request は `abandonInboundRequest()`
+  で解放します；
+- `getRemoteError()` は明示的 raw
+  data 境界で、Adapter による検証と redaction が必要です。
+
+## 既定の境界
+
+- message、未読 inbound、pending request、remote request、write は有限です；
+- request timeout は既定で 30 秒、timer は Node の安全範囲に制限されます；
+- 一つの JSON object を含む JSONL frame のみで、batch
+  array と複数行 frame は拒否します；
+- JSON-RPC `"2.0"` の必須化・送信や整数 numeric ID の強制を選択できます。
+
+Stream と process は呼び出し側が所有します。`close()`
+は Stream を直接終了せず、logical connection を閉じ、任意の `cleanup`
+を最大一回実行します。`AbortSignal` と timeout は local
+wait だけを止め、Provider cancellation の証拠にはなりません。
+
+## Error と機密データ
+
+不正 JSON、無効 UTF-8、上限超過、重複 remote request ID、早期 EOF は fail
+closed です。`JsonRpcTransportError` は frame、ID、Stream
+Error を保持しません。remote error、`method`、`params` は untrusted Provider
+data なので、記録や mapping の前に Adapter が検証・redact します。
+
+このパッケージは process manager、Provider Adapter、retry layer、Agent
+Loop ではありません。全設定と制限は[英語の詳細ドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/transport-jsonrpc-stdio`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-jsonrpc-stdio</code></h1>
+
+<p align="center"><strong>Bounded bidirectional JSONL RPC over caller-owned Node streams.</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-jsonrpc-stdio"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-jsonrpc-stdio/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-jsonrpc-stdio"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-jsonrpc-stdio?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-jsonrpc-stdio` is a bounded, bidirectional JSONL transport
 for Provider Adapters whose official machine interface exchanges JSON-RPC-shaped
@@ -9,6 +28,14 @@ backpressure, local wait controls, and connection disposal. It does not import
 Provider SDKs or assign portable Harapter meaning to Provider methods and
 payloads.
 
+## Use this package when
+
+- an official harness interface speaks newline-delimited JSON-RPC-shaped
+  messages over stdin/stdout or equivalent streams;
+- your Adapter needs bounded request correlation, backpressure, remote requests,
+  and deterministic cleanup; or
+- you need strict transport errors without leaking frames or upstream messages.
+
 ## Installation
 
 ```bash
@@ -120,7 +147,7 @@ object itself through ordinary JSON serialization or Node inspection remains
 content-free. Inbound `method` and `params` have the same Provider-owned
 validation and redaction requirement.
 
-## Example
+## Quick start
 
 ```ts
 import { JsonRpcStdioTransport } from '@harapter/transport-jsonrpc-stdio';

package/README.zh-CN.md

@@ -0,0 +1,86 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-jsonrpc-stdio</code></h1>
+
+<p align="center"><strong>在调用方拥有的 Node Stream 上提供有界双向 JSONL RPC。</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-jsonrpc-stdio"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-jsonrpc-stdio/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-jsonrpc-stdio"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-jsonrpc-stdio?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 -->
+
+这个传输包面向通过 stdin/stdout 或等价 Node
+Stream 交换一行一个 JSON 对象的 Provider
+Adapter。它负责 framing、请求关联、有序入站消息、背压、超时和清理，但不解释 Provider 方法，也不生成 Harapter
+Session、Run 或终态。
+
+## 安装
+
+```bash
+pnpm add @harapter/transport-jsonrpc-stdio@next
+```
+
+## 快速开始
+
+```ts
+import { JsonRpcStdioTransport } from '@harapter/transport-jsonrpc-stdio';
+
+const transport = new JsonRpcStdioTransport({
+  readable: controlledProcess.stdout,
+  writable: controlledProcess.stdin,
+  cleanup: () => stopControlledProcess(controlledProcess),
+});
+
+const incoming = (async () => {
+  for await (const message of transport.incoming()) {
+    await validateAndMapProviderMessage(message);
+  }
+})();
+
+const initialized = await transport.request('initialize', {
+  clientInfo: { name: 'harapter-provider', version: 'current' },
+});
+
+await validateInitializeResult(initialized);
+await transport.close();
+await incoming;
+```
+
+## 常见用法
+
+- `request()` 发送请求并等待匹配响应；`notify()` 只写通知；
+- `incoming()` 由唯一消费者处理远端请求与通知；
+- 需要“终态响应之前的事件均已处理”时使用 `requestAfterInbound()`；
+- Provider 已在别处权威解决远端请求时，用 `abandonInboundRequest()` 释放容量；
+- `getRemoteError()` 是显式原始数据边界，返回值必须由 Adapter 校验和脱敏。
+
+## 默认边界
+
+- 单条消息、未读消息、待处理请求、入站请求和写操作均有有限上限；
+- 默认请求等待 30 秒，所有 timer 值必须在 Node 可安全表示的范围内；
+- 只接受单个 JSON 对象的 JSONL frame，不支持 batch array 或多行 frame；
+- 可要求并发送精确的 JSON-RPC `"2.0"`，也可要求整数 numeric ID。
+
+调用方拥有 Stream 和进程。`close()`
+不会直接结束或销毁 Stream，只会关闭逻辑连接并最多调用一次可选
+`cleanup`。`AbortSignal`
+和 timeout 只终止本地等待，不会发送 Provider 取消，也不能证明远端工作已经停止。
+
+## 错误与敏感数据
+
+畸形 JSON、无效 UTF-8、超限消息、重复入站请求 ID 和提前 EOF 会 fail closed。
+`JsonRpcTransportError` 不附带原始 frame、标识符或 Stream Error。远端 error、
+`method` 和 `params` 仍是不可信 Provider 数据，Adapter 必须在记录或映射前脱敏。
+
+该包不是进程管理器、Provider Adapter、重试层或通用 Agent
+Loop。完整限制与所有配置项见[英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/transport-jsonrpc-stdio",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Bounded bidirectional JSONL RPC transport 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-jsonrpc-stdio#readme",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "README.zh-CN.md",
+    "README.ja.md"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",