@harapter/transport-jsonl-process 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,81 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-jsonl-process</code></h1>
+
+<p align="center"><strong>process-based Harness protocol 向けの strict bounded JSONL transport。</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-jsonl-process"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-jsonl-process/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-jsonl-process"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-jsonl-process?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 -->
+
+非 JSON-RPC の process protocol に、strict JSONL
+framing、順序付き inbound、serialized
+write、backpressure、timeout、cleanup を提供します。process 起動、request
+correlation、message の意味、redaction、Harapter mapping は Provider
+Adapter が所有します。
+
+## インストール
+
+```bash
+pnpm add @harapter/transport-jsonl-process@next
+```
+
+## クイックスタート
+
+```ts
+import { JsonlProcessTransport } from '@harapter/transport-jsonl-process';
+
+const transport = new JsonlProcessTransport({
+  readable: controlledProcess.stdout,
+  writable: controlledProcess.stdin,
+  cleanup: () => stopControlledProcess(controlledProcess),
+});
+
+const incoming = (async () => {
+  for await (const message of transport.incoming()) {
+    await validateAndMapProviderMessage(message);
+  }
+})();
+
+await transport.send({ id: 'request-1', type: 'prompt', message: 'Hello' });
+await transport.close();
+await incoming;
+```
+
+## 動作境界
+
+- 一つの UTF-8 JSON object を一つの LF record とし、CRLF も受け入れます；
+- 空 record、array、primitive、無効 UTF-8、不正 JSON、切れた最終 record は失敗します；
+- 既定値は message 1 MiB、未読 message 128、pending write 128、write wait
+  30 秒です；
+- `send()` 成功は Node write
+  callback の完了だけを示し、Provider の受理や完了を示しません；
+- `incoming()` の consumer は一つだけで、consumer 終了は logical
+  connection を閉じます。
+
+Stream は呼び出し側が所有します。Transport は spawn、kill、restart、end、destroy を行いません。任意の
+`cleanup`
+は明示 close または終端 failure 後に最大一回だけ実行されます。timeout と
+`AbortSignal` は local write wait のみを制御します。
+
+## Error と安全性
+
+`JsonlTransportError` は固定の content-free
+message を使い、frame、ID、path、Stream Error、Provider
+Payload を保持しません。inbound object は untrusted
+data なので、Event、Error、Fixture、log にする前に Adapter が検証・redact します。
+
+process manager、request/response protocol、Provider Adapter、retry layer、Agent
+Loop ではありません。全設定と lifecycle は[英語の詳細ドキュメント](./README.md)
+を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/transport-jsonl-process`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-jsonl-process</code></h1>
+
+<p align="center"><strong>Strict, bounded JSONL messaging for process-backed harness protocols.</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-jsonl-process"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-jsonl-process/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-jsonl-process"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-jsonl-process?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-jsonl-process` is a bounded strict-JSONL transport for
 Provider Adapters that communicate with a host-supplied harness process.
@@ -9,6 +28,14 @@ limits. It does not spawn or discover executables, correlate protocol requests,
 interpret Provider messages, or assign Harapter Session, Run, Event, error, or
 cancellation semantics.
 
+## Use this package when
+
+- a harness exchanges one JSON object per line without JSON-RPC correlation;
+- your Adapter owns the process protocol but needs safe framing, bounded queues,
+  serialized writes, and cleanup; or
+- malformed, oversized, or truncated input must fail closed without leaking the
+  original payload.
+
 ## Installation
 
 ```bash
@@ -75,7 +102,7 @@ contain sensitive data. The consuming Provider Adapter must validate and redact
 them before producing Harapter events, errors, diagnostics, logs, fixtures, or
 raw-channel observations.
 
-## Example
+## Quick start
 
 ```ts
 import { JsonlProcessTransport } from '@harapter/transport-jsonl-process';

package/README.zh-CN.md

@@ -0,0 +1,74 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/transport-jsonl-process</code></h1>
+
+<p align="center"><strong>面向进程型 Harness 协议的严格、有界 JSONL 传输。</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-jsonl-process"><img src="https://img.shields.io/npm/v/%40harapter%2Ftransport-jsonl-process/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/transport-jsonl-process"><img src="https://img.shields.io/npm/dm/%40harapter%2Ftransport-jsonl-process?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 -->
+
+这个包为非 JSON-RPC 的进程协议提供严格 JSONL
+framing、有序入站迭代、串行写入、背压、超时和清理。Provider
+Adapter 仍然负责启动进程、关联请求、解释消息、脱敏以及映射 Harapter 生命周期。
+
+## 安装
+
+```bash
+pnpm add @harapter/transport-jsonl-process@next
+```
+
+## 快速开始
+
+```ts
+import { JsonlProcessTransport } from '@harapter/transport-jsonl-process';
+
+const transport = new JsonlProcessTransport({
+  readable: controlledProcess.stdout,
+  writable: controlledProcess.stdin,
+  cleanup: () => stopControlledProcess(controlledProcess),
+});
+
+const incoming = (async () => {
+  for await (const message of transport.incoming()) {
+    await validateAndMapProviderMessage(message);
+  }
+})();
+
+await transport.send({ id: 'request-1', type: 'prompt', message: 'Hello' });
+await transport.close();
+await incoming;
+```
+
+## 行为边界
+
+- 每条记录必须是一个 UTF-8 JSON 对象，以 LF 结尾；CRLF 也可接受；
+- 空记录、array、primitive、无效 UTF-8、畸形 JSON 和截断的尾记录会关闭连接；
+- 默认消息 1 MiB、未读消息 128、待写操作 128，写等待 30 秒；
+- `send()` 成功只表示 Node 写回调完成，不表示 Provider 已接受或完成工作；
+- 只有一个调用方可以消费 `incoming()`，停止消费会关闭逻辑连接。
+
+调用方拥有 Stream。Transport 不会 spawn、kill、restart、end 或 destroy；可选
+`cleanup` 由显式关闭或终态失败触发，最多执行一次。timeout 与 `AbortSignal`
+仅控制本地写等待，不会发出 Provider 取消。
+
+## 错误与安全
+
+`JsonlTransportError`
+使用固定、不含内容的错误消息，不保留 frame、标识符、路径、Stream
+Error 或 Provider
+Payload。入站对象仍是不可信数据，必须由 Adapter 在生成 Event、Error、Fixture 或日志前校验和脱敏。
+
+该包不是进程管理器、请求响应协议、Provider Adapter、重试层或 Agent
+Loop。完整配置和生命周期细节见[英文详细文档](./README.md)。

package/package.json

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