@harapter/adapter-openclaw 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,106 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-openclaw</code></h1>
+
+<p align="center"><strong>stable ACP v1 で isolated OpenClaw Gateway Session を駆動します。</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-openclaw"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-openclaw/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-openclaw"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-openclaw?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-openclaw` は公式 `openclaw acp` stdio Bridge を起動し、stable
+ACP
+v1 の Session、Prompt、Event、Permission、Resume、cancellation を Harapter に mapping します。OpenClaw
+Gateway の導入、設定、認証、運用はホストが行います。
+
+## インストール
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-openclaw@next
+```
+
+## クイックスタート
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  OPENCLAW_PROVIDER_ID,
+  createOpenClawProviderFactory,
+} from '@harapter/adapter-openclaw';
+
+const registry = new HarnessRegistry();
+registry.register(createOpenClawProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('openclaw-local'),
+  providerId: OPENCLAW_PROVIDER_ID,
+  displayName: 'OpenClaw',
+  connection: {
+    kind: 'process',
+    command: 'openclaw',
+    args: ['acp'],
+    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
+
+- initialize は stable ACP v1 と implementation name `openclaw-acp`
+  を検証します；
+- 新 Session は isolated Gateway Session Key を持ち、native
+  ID と route は Profile に束縛されます；
+- Resume には同じ Provider、Profile、Compatibility、isolated route が必要です；
+- ACP Connection 全体で active Run は一つです；
+- text と handshake が許す Image Reference を扱い、Generic File/Native
+  Input は対象外です；
+- validated ACP Prompt Response だけが terminal authority です；
+- `run.cancel()` は authoritative `cancelled` Response で native
+  cancellation になります；
+- valid Permission Request を観測すると Approval Capability が `unknown` から
+  `native` になります；
+- 未知 ACP message は bounded redacted observation になり、Prompt、path、Tool
+  content を保持しません。
+
+local timeout/abort で remote
+mutation を確認できない場合、Connection を abort し、cancellation や success にはしません。`end_turn`
+は完了、`refusal`、`max_tokens`、 `max_turn_requests` は失敗、EOF、Process
+Loss、Queue Overflow は `connection_aborted` です。
+
+## Compatibility と制限
+
+stable ACP v1 は negotiated protocol version を持つため、connection 時に Runtime
+identity と必須 structure を検証できます。Fixture、Provider Negative、shared
+conformance、real completion、cross-Client Resume、Native
+Cancellation の evidence があります。
+
+shared Gateway routing、History Replay、Session MCP、Audio、Generic
+File、Filesystem/ Terminal Client Service、自動 Process Restart、直接 Gateway
+WebSocket は対象外です。Workspace は ACP に渡しますが Tool の実行 Directory は
+`unknown` です。詳細は [英語のドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/adapter-openclaw`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-openclaw</code></h1>
+
+<p align="center"><strong>Drive an isolated OpenClaw Gateway Session through stable ACP 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/adapter-openclaw"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-openclaw/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-openclaw"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-openclaw?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-openclaw` maps the official `openclaw acp` stdio bridge to
 the portable Harapter lifecycle.
@@ -8,6 +27,14 @@ Gateway. Harapter starts only the exact adapter-owned command selected by the
 Profile. It does not install an OpenClaw Runtime or SDK, configure models or
 tools, manage Gateway credentials, or change host security policy.
 
+## Use this Adapter when
+
+- your host already operates an authenticated OpenClaw Gateway;
+- you need one isolated Gateway Session exposed as a portable Session over the
+  stable ACP v1 bridge; or
+- you need resume, native cancellation, approvals, and unknown ACP observations
+  without direct Gateway WebSocket coupling.
+
 ## Installation
 
 ```bash

package/README.zh-CN.md

@@ -0,0 +1,102 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-openclaw</code></h1>
+
+<p align="center"><strong>通过稳定 ACP v1 驱动隔离的 OpenClaw Gateway Session。</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-openclaw"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-openclaw/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-openclaw"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-openclaw?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-openclaw` 启动官方 `openclaw acp` stdio Bridge，将稳定 ACP v1
+Session、Prompt、Event、Permission、Resume 与取消映射为 Harapter。宿主负责安装、配置、认证和运行 OpenClaw
+Gateway。
+
+## 安装
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-openclaw@next
+```
+
+## 快速开始
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  OPENCLAW_PROVIDER_ID,
+  createOpenClawProviderFactory,
+} from '@harapter/adapter-openclaw';
+
+const registry = new HarnessRegistry();
+registry.register(createOpenClawProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('openclaw-local'),
+  providerId: OPENCLAW_PROVIDER_ID,
+  displayName: 'OpenClaw',
+  connection: {
+    kind: 'process',
+    command: 'openclaw',
+    args: ['acp'],
+    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
+
+- 初始化必须协商稳定 ACP v1，并验证 Implementation Name 为 `openclaw-acp`；
+- 新 Session 使用显式隔离的 Gateway Session Key，Native
+  ID 和路由状态绑定到 Profile；
+- Resume 要求相同 Provider、Profile、Compatibility 与隔离 Route；
+- 整条 ACP Connection 同时只运行一个 Run，避免未知 Event 被错误分配；
+- 支持非空文本和握手声明的 Image Reference，Generic File 与 Native
+  Input 不受支持；
+- 验证通过的 ACP Prompt Response 是唯一终态 Authority；
+- `run.cancel()` 必须得到 Authoritative `cancelled` Response 才是 Native
+  Cancel；
+- Permission Request 动态把 Approval Capability 从 `unknown` 提升为 `native`；
+- 未知 ACP 消息通过有界、脱敏 Observation 保持可见，不保存 Prompt、路径或 Tool 内容。
+
+本地 timeout/abort 无法确认远端 Mutation 时，Adapter 会中止 Connection，绝不把它当成取消或成功。`end_turn`
+是完成；`refusal`、`max_tokens` 和 `max_turn_requests` 是失败；EOF、Process
+Loss 与 Queue Overflow 是 `connection_aborted`。
+
+## 兼容性与限制
+
+稳定 ACP
+v1 提供可协商协议版本，因此 Runtime 身份和必需结构可在连接阶段验证。当前 Adapter 有 Fixture、Provider
+Negative、共享 Conformance，以及真实完成、跨 Client Resume 和 Native
+Cancellation Evidence。
+
+当前不覆盖共享 Gateway Session 路由、History Replay、Session MCP、Audio、Generic
+File、Filesystem/Terminal Client Service、自动 Process Restart 或直接 Gateway
+WebSocket。Workspace 会传给 ACP，但 Tool 实际执行目录仍为
+`unknown`。完整 Evidence、Live Test、安全隔离与 Native
+Extension 见[英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/adapter-openclaw",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenClaw ACP 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/openclaw#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,12 +43,12 @@
     "tag": "next"
   },
   "dependencies": {
-    "@harapter/core": "0.1.1",
-    "@harapter/transport-acp": "0.1.1",
-    "@harapter/transport-jsonrpc-stdio": "0.1.1"
+    "@harapter/core": "0.1.2",
+    "@harapter/transport-acp": "0.1.2",
+    "@harapter/transport-jsonrpc-stdio": "0.1.2"
   },
   "devDependencies": {
-    "@harapter/conformance": "0.1.1"
+    "@harapter/conformance": "0.1.2"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json"