@harapter/adapter-opencode 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,107 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-opencode</code></h1>
+
+<p align="center"><strong>ホスト運用の OpenCode HTTP/SSE Server を 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-opencode"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-opencode/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-opencode"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-opencode?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-opencode` は stable `opencode serve`
+HTTP/OpenAPI と SSE を Harapter
+lifecycle に mapping します。Server の導入、認証、起動、停止はホストが行い、Adapter は指定 Endpoint だけに接続して remote
+Session を暗黙削除しません。
+
+## インストール
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-opencode@next
+```
+
+## クイックスタート
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  OPENCODE_PROVIDER_ID,
+  createOpenCodeProviderFactory,
+} from '@harapter/adapter-opencode';
+
+const registry = new HarnessRegistry();
+registry.register(createOpenCodeProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('opencode-local'),
+  providerId: OPENCODE_PROVIDER_ID,
+  displayName: 'OpenCode',
+  connection: {
+    kind: 'endpoint',
+    url: 'http://127.0.0.1:4096/',
+    transport: 'http',
+    ownership: 'external',
+  },
+});
+
+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();
+  }
+}
+```
+
+認証する場合は Connection に `authRef` を置き、Factory の `resolveAuthHeaders`
+でホストが解決します。Harapter は Header 値を記録・保存・返却しません。
+
+## Session、Run、Input
+
+- Session は Directory に束縛され、File Workspace URI は OpenCode
+  Directory になります；
+- `session.close()` は local handle だけを解放し、remote DELETE
+  Route を呼びません；
+- absolute URI と `mediaType` を持つ text/File/Image Reference を stable
+  Part に mapping します；
+- Session ごとに active Run は一つで、同期 Message
+  Request の前に SSE を開きます；
+- synchronous Message Response だけが success authority で、`session.idle`
+  は代替できません；
+- `run.cancel()` は Abort Route と `MessageAbortedError` の両方で native
+  cancellation になります；
+- Permission Event は Approval に mapping し、`once`、`reject`、明示的 `always`
+  を区別します。
+
+remote
+settlement が不確実な場合、Adapter は Session を quarantine し、誤った再利用を防ぎます。stream
+loss、HTTP Error、不正 Event、未知 Terminal は success になりません。
+
+## Compatibility と制限
+
+接続時に Health を検証し、使用する Session、Message、Abort、Permission、Event
+Shape を実行時に検証します。Runtime
+Version は診断情報であり allowlist ではありません。
+
+stable interface には Fixture、negative test、shared conformance、live
+evidence があります。automatic SSE reconnect、OpenCode process 管理、portable
+close による remote deletion、Command/Plugin の Core
+Capability 化は対象外です。詳細は
+[英語のドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/adapter-opencode`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-opencode</code></h1>
+
+<p align="center"><strong>Connect a host-operated OpenCode HTTP/SSE server to 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-opencode"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-opencode/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-opencode"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-opencode?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-opencode` maps the current documented stable `opencode serve`
 HTTP/OpenAPI and Server-Sent Events interface to Harapter Core.
@@ -7,6 +26,13 @@ The host installs, configures, authenticates, starts, and stops OpenCode. The
 Adapter connects only to a host-selected HTTP endpoint and never invokes a
 runtime installation, server disposal, or Session deletion route implicitly.
 
+## Use this Adapter when
+
+- your host already operates an `opencode serve` endpoint;
+- you need directory-bound Sessions, streamed Events, native abort, permissions,
+  and file or image references through the portable lifecycle; or
+- authentication and server process ownership must remain outside Harapter.
+
 ## Installation
 
 ```bash

package/README.zh-CN.md

@@ -0,0 +1,96 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-opencode</code></h1>
+
+<p align="center"><strong>把宿主运行的 OpenCode HTTP/SSE Server 接入 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.zh-CN.md">Harapter</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@harapter/adapter-opencode"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-opencode/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-opencode"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-opencode?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-opencode` 将当前稳定的 `opencode serve`
+HTTP/OpenAPI 与 SSE 接口映射为 Harapter 生命周期。宿主负责安装、认证、启动和停止 Server；Adapter 只连接指定 Endpoint，不会隐式删除远端 Session。
+
+## 安装
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-opencode@next
+```
+
+## 快速开始
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  OPENCODE_PROVIDER_ID,
+  createOpenCodeProviderFactory,
+} from '@harapter/adapter-opencode';
+
+const registry = new HarnessRegistry();
+registry.register(createOpenCodeProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('opencode-local'),
+  providerId: OPENCODE_PROVIDER_ID,
+  displayName: 'OpenCode',
+  connection: {
+    kind: 'endpoint',
+    url: 'http://127.0.0.1:4096/',
+    transport: 'http',
+    ownership: 'external',
+  },
+});
+
+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();
+  }
+}
+```
+
+需要认证时，在 Connection 中放 `authRef`，并通过 Factory 的 `resolveAuthHeaders`
+由宿主解析。Harapter 不记录、持久化或返回 Header 值。
+
+## Session、Run 与输入
+
+- Session 与目录绑定；File Workspace URI 会成为 OpenCode Directory；
+- `session.close()` 只释放本地 Handle，不调用删除远端数据的 DELETE Route；
+- 文本、带绝对 URI 和 `mediaType` 的 File/Image Reference 可以映射为稳定 Part；
+- 一次 Session 只允许一个 Run，SSE 在同步 Message Request 前打开；
+- 同步 Message Response 是成功终态的唯一 Authority，`session.idle` 不能代替它；
+- `run.cancel()` 只有 Abort Route 成功且 Message Response 为
+  `MessageAbortedError` 时才是原生取消；
+- Permission Event 映射为 Approval，`once`、`reject` 与显式 `always` 保持区别。
+
+如果 Run 远端状态不确定，Adapter 会隔离对应 Session，防止后续工作错误复用它。断流、HTTP
+Error、畸形 Event 和未知 Terminal Shape 绝不会变成 `run.completed`。
+
+## 兼容性与限制
+
+连接时校验 Health，使用到的 Session、Message、Abort、Permission 和 Event
+Shape 都会在运行时校验。Runtime Version 只用于诊断，不是能力推断或白名单。
+
+当前稳定接口已有 Fixture、负例、共享 Conformance 和 Live
+Evidence。不支持自动 SSE 重连、OpenCode Process 管理、Portable
+Close 删除远端 Session，以及把 Command 或 Plugin 宣称为 Core
+Capability。详细选项、证据版本和 Native Client 见 [英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/adapter-opencode",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenCode HTTP 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/opencode#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-http-sse": "0.1.1"
+    "@harapter/core": "0.1.2",
+    "@harapter/transport-http-sse": "0.1.2"
   },
   "devDependencies": {
-    "@harapter/conformance": "0.1.1"
+    "@harapter/conformance": "0.1.2"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json"