@harapter/adapter-pi 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,105 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-pi</code></h1>
+
+<p align="center"><strong>Pi Agent の strict JSONL RPC mode を Harapter から実行します。</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/adapter-pi"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-pi/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-pi"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-pi?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/adapter-pi` は公式 Pi Agent `--mode rpc`
+を Harapter に mapping します。Session ごとに独立 Process を使い、stream
+Event、persisted Resume、native Abort を提供します。Extension、Skill、Prompt
+Template discovery は無効化されます。
+
+## 前提条件とインストール
+
+Pi Agent の導入、設定、認証、Model、absolute executable
+path はホストが所有します。Harapter は Session
+File や Credential を読み取らず Runtime を導入しません。
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-pi@next
+```
+
+## クイックスタート
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import { PI_PROVIDER_ID, createPiProviderFactory } from '@harapter/adapter-pi';
+
+const registry = new HarnessRegistry();
+registry.register(createPiProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('pi-local'),
+  providerId: PI_PROVIDER_ID,
+  displayName: 'Pi Agent',
+  connection: {
+    kind: 'process',
+    command: '/opt/harapter-runtimes/bin/pi',
+    args: [],
+    ownership: 'adapter',
+  },
+});
+
+const session = await client.createSession();
+try {
+  const run = await session.start({
+    parts: [{ type: 'text', text: 'Describe the current project.' }],
+  });
+  for await (const event of run.events()) console.log(event.type);
+  console.log((await run.result()).status);
+} finally {
+  try {
+    await session.close();
+  } finally {
+    await client.close();
+  }
+}
+```
+
+## Process、Session、Run
+
+- `--version` probe 後、Session ごとに独立 RPC Process を起動します；
+- `--no-extensions --no-skills --no-prompt-templates --mode rpc` を追加します；
+- `persistSessions: false` は `--no-session` を追加して Resume を無効にします；
+- Resume は Native ID で新 Process を開き、同じ Session の返却を要求します；
+- Workspace、System Context、Session Model、Metadata は unsupported です；
+- Run は text のみで、複数 part は改行結合し、`/`
+  から始まる input は拒否します；
+- `prompt` Response は受付だけで、`agent_settled` と最後の valid Assistant
+  `message_end` が terminal authority です；
+- `run.cancel()` は `abort` Response と `stopReason: 'aborted'`
+  の相関で native になります；
+- Tool ID は hash され、Tool Argument/Result は portable Event に残りません。
+
+Pi Extension UI の select、confirm、input、editor は Provider
+Interaction ですが、generic Approval/User Input
+Capability にはしません。未知 Event は bounded redacted
+observation に残り、Native Client は ownership-preserving read
+command のみです。
+
+## Compatibility と制限
+
+Pi RPC は Runtime Version を返しますが negotiated protocol
+version はありません。Version は lock せず、使用する Response、Event、Terminal
+Structure を検証します。そのため状態は `experimental` ですが、real
+completion、Resume、Native Cancel、cleanup の evidence はあります。
+
+Image/File、Portable Model、Workspace、generic Approval、Runtime
+Extension/Skill、shared Process、Session multiplex、auto restart、Session
+File、任意 native mutation は対象外です。全 options、live test、検証 Version は
+[英語の詳細ドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/adapter-pi`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-pi</code></h1>
+
+<p align="center"><strong>Run Pi Agent's strict JSONL RPC mode through Harapter.</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/adapter-pi"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-pi/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-pi"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-pi?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/adapter-pi` maps the official Pi Agent RPC mode to the portable
 Harapter lifecycle.
@@ -8,6 +27,14 @@ starts only the exact adapter-owned command selected by the Profile. It does not
 install a Pi Runtime or SDK, select models, manage credentials, read Session
 files, or change host security policy.
 
+## Use this Adapter when
+
+- your host supplies the official Pi Agent executable in strict RPC mode;
+- you need one isolated process per Session with streamed Events, persisted
+  resume, and native abort; or
+- you want Pi-specific reads and UI interactions behind explicit native and
+  Provider-extension boundaries.
+
 ## Installation
 
 ```bash

package/README.zh-CN.md

@@ -0,0 +1,102 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-pi</code></h1>
+
+<p align="center"><strong>通过 Harapter 运行 Pi Agent 的严格 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/adapter-pi"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-pi/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-pi"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-pi?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/adapter-pi` 将官方 Pi Agent `--mode rpc`
+接口映射为 Harapter。每个 Session 使用独立进程，支持流式 Event、持久化 Resume 和原生 Abort，同时禁用 Extension、Skill 与 Prompt
+Template 自动发现，防止普通文本绕过 Agent 生命周期。
+
+## 前置条件与安装
+
+宿主安装、配置并认证 Pi
+Agent，选择模型和绝对可执行文件路径。Harapter 不读取 Session
+File、不管理 Credential，也不会安装 Runtime。
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-pi@next
+```
+
+## 快速开始
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import { PI_PROVIDER_ID, createPiProviderFactory } from '@harapter/adapter-pi';
+
+const registry = new HarnessRegistry();
+registry.register(createPiProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('pi-local'),
+  providerId: PI_PROVIDER_ID,
+  displayName: 'Pi Agent',
+  connection: {
+    kind: 'process',
+    command: '/opt/harapter-runtimes/bin/pi',
+    args: [],
+    ownership: 'adapter',
+  },
+});
+
+const session = await client.createSession();
+try {
+  const run = await session.start({
+    parts: [{ type: 'text', text: 'Describe the current project.' }],
+  });
+  for await (const event of run.events()) console.log(event.type);
+  console.log((await run.result()).status);
+} finally {
+  try {
+    await session.close();
+  } finally {
+    await client.close();
+  }
+}
+```
+
+## 进程、Session 与 Run
+
+- Adapter 探测 `--version`，再为每个 Session 启动独立 RPC Process；
+- 自动追加 `--no-extensions --no-skills --no-prompt-templates --mode rpc`；
+- `persistSessions: false` 会加 `--no-session` 并关闭 Resume；
+- Resume 会用 Native ID 启动新进程，并要求 Runtime 返回相同 Session；
+- Workspace、System Context、Session Model 与 Metadata 不受支持；
+- Portable Run 只接受文本，多段文本用换行连接；以 `/` 开头的输入会被拒绝；
+- `prompt` Response 只表示接受，`agent_settled` 和最后一个有效 Assistant
+  `message_end` 共同提供终态 Authority；
+- `run.cancel()` 只有 `abort` Response 与 `stopReason: 'aborted'`
+  终态相关联时才是 Native Cancel；
+- Tool ID 会散列，Tool Argument/Result 不进入 Portable Event。
+
+Pi Extension UI 的 select、confirm、input 和 editor 会映射为 Provider
+Interaction，但不被提升为通用 Approval 或 User Input
+Capability。未知 Event 会进入有界、脱敏的 Observation；Native
+Client 只提供保持所有权的只读命令。
+
+## 兼容性与限制
+
+Pi RPC 会报告语义化 Runtime
+Version，但没有可协商的协议版本。Adapter 不锁版本，会校验每个实际使用的 Response、Event 和 Terminal
+Structure；因此当前状态为 `experimental`，同时已有真实完成、Resume、Native
+Cancel 与清理 Evidence。
+
+不支持 Image/File Input、Portable Model、Workspace、通用 Approval、Runtime
+Extension/Skill、共享 Process、多 Session Multiplex、自动重启、Session File
+Access 或任意 Native Mutation。完整 Options、Live Test 和最后验证版本见
+[英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/adapter-pi",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Pi Agent RPC provider adapter for Harapter.",
   "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/providers/pi#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,11 +43,11 @@
     "tag": "next"
   },
   "dependencies": {
-    "@harapter/core": "0.1.1",
-    "@harapter/transport-jsonl-process": "0.1.1"
+    "@harapter/core": "0.1.2",
+    "@harapter/transport-jsonl-process": "0.1.2"
   },
   "devDependencies": {
-    "@harapter/conformance": "0.1.1"
+    "@harapter/conformance": "0.1.2"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json"