@harapter/adapter-codex 0.1.1 → 0.1.2

package/README.ja.md

@@ -0,0 +1,115 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-codex</code></h1>
+
+<p align="center"><strong>stable Codex App 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-codex"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-codex/next?style=flat-square&amp;label=npm%20next" alt="npm next バージョン"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-codex"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-codex?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-codex` は公式 stable App
+Server に接続し、Thread、Turn、stream Event、Interaction、終端、native
+interrupt を Harapter API に mapping します。人向け CLI
+output の scraping は行いません。
+
+## 前提条件
+
+Codex の導入と認証はホストが行います。Adapter は Binary を含まず、credential や
+`SecretRef` を読み取らず、Sandbox と Approval Policy を勝手に選びません。
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-codex@next
+```
+
+## クイックスタート
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  CODEX_PROVIDER_ID,
+  createCodexProviderFactory,
+} from '@harapter/adapter-codex';
+
+const registry = new HarnessRegistry();
+registry.register(createCodexProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('codex-local'),
+  providerId: CODEX_PROVIDER_ID,
+  displayName: 'Local Codex',
+  connection: {
+    kind: 'process',
+    command: 'codex',
+    args: ['app-server', '--stdio'],
+    ownership: 'adapter',
+  },
+  requiredCapabilities: [{ name: 'input.text' }, { name: 'run.stream' }],
+});
+
+const session = await client.createSession({
+  providerOptions: {
+    approvalPolicy: 'never',
+    sandbox: 'read-only',
+    ephemeral: true,
+  },
+});
+
+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();
+  }
+}
+```
+
+## Mapping と利用例
+
+- Codex Thread が Session、Turn が Run で、一つの Thread に active
+  Turn は一つです；
+- text と Image Reference は portable、任意 File Reference は unsupported です；
+- stable Command/File Change Request は Approval
+  Interaction に mapping されます；
+- `session.ref()` は同じ Provider、Profile、互換 App
+  Server だけに resume できます；
+- `run.cancel()` は `turn/interrupt` 後の authoritative `interrupted`
+  でだけ native cancellation です；
+- `CodexNativeClient` は明示的 Provider 機能を提供しますが portable
+  guarantee は持ちません。
+
+`turn/completed`
+だけが終端 authority です。未知・不正な terminal は success にならず、process
+exit、EOF、Client Close、未確認 interrupt は `connection_aborted` になります。
+
+## 設定と安全性
+
+Profile は Adapter-owned `process`
+connection のみです。message、queue、request、cancel settlement、Run
+Event の上限を設定でき、未知 option は拒否します。Event
+consumer が止まり queue が満杯になると、drop せず connection を abort します。
+
+Error は Provider Message、Prompt、file content、credential、environment、local
+path を含みません。未知 notification は bounded redacted raw
+channel に残ります。
+
+stable App Server には Fixture、mapping test、shared conformance、live Runtime
+Evidence があります。正確な compatibility、options、live test、制限は
+[英語の詳細ドキュメント](./README.md)を参照してください。

package/README.md

@@ -1,4 +1,23 @@
-# `@harapter/adapter-codex`
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-codex</code></h1>
+
+<p align="center"><strong>Run the stable Codex App Server through Harapter's portable lifecycle.</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-codex"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-codex/next?style=flat-square&amp;label=npm%20next" alt="npm next version"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-codex"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-codex?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-codex` exposes the official Codex harness through the stable
 [Codex App Server](https://developers.openai.com/codex/app-server) interface and
@@ -6,6 +25,15 @@ maps it to the portable Harapter lifecycle. The harness and App Server source
 live in the open-source
 [OpenAI Codex repository](https://github.com/openai/codex).
 
+## Use this Adapter when
+
+- a host application needs Codex alongside other harnesses behind the same
+  portable lifecycle;
+- you need stable App Server Sessions, streamed Turns, approvals, resume, and
+  native interruption without scraping CLI text; or
+- you want Codex-specific behavior available through typed extensions while
+  keeping application orchestration Provider-agnostic.
+
 ## Installation
 
 ```bash
@@ -66,17 +94,24 @@ const client = await registry.connect({
 });
 
 const session = await client.createSession();
-const run = await session.start({
-  parts: [{ type: 'text', text: 'Describe the current project.' }],
-});
-
-for await (const event of run.events()) {
-  // Render or persist according to the host's data policy.
+try {
+  const run = await session.start({
+    parts: [{ type: 'text', text: 'Describe the current project.' }],
+  });
+
+  for await (const event of run.events()) {
+    // Render or persist according to the host's data policy.
+  }
+
+  const result = await run.result();
+  console.log(result.status);
+} finally {
+  try {
+    await session.close();
+  } finally {
+    await client.close();
+  }
 }
-
-const result = await run.result();
-await session.close();
-await client.close();
 ```
 
 ## Profile and process ownership

package/README.zh-CN.md

@@ -0,0 +1,109 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
+<h1 align="center"><code>@harapter/adapter-codex</code></h1>
+
+<p align="center"><strong>通过 Harapter 可移植生命周期运行稳定版 Codex App Server。</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-codex"><img src="https://img.shields.io/npm/v/%40harapter%2Fadapter-codex/next?style=flat-square&amp;label=npm%20next" alt="npm next 版本"></a>
+  <a href="https://www.npmjs.com/package/@harapter/adapter-codex"><img src="https://img.shields.io/npm/dm/%40harapter%2Fadapter-codex?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-codex` 连接 Codex 官方稳定 App
+Server，把 Thread、Turn、流式 Event、Interaction、终态和原生中断映射为 Harapter
+API。它使用公开机器接口，不解析面向人的 CLI 文本。
+
+## 前置条件
+
+宿主负责安装并认证 Codex。Adapter 不包含 Codex Binary、不读取凭据、不解析
+`SecretRef`，也不替宿主选择 Sandbox 或 Approval Policy。
+
+```bash
+pnpm add @harapter/core@next @harapter/adapter-codex@next
+```
+
+## 快速开始
+
+```ts
+import { HarnessRegistry, profileId } from '@harapter/core';
+import {
+  CODEX_PROVIDER_ID,
+  createCodexProviderFactory,
+} from '@harapter/adapter-codex';
+
+const registry = new HarnessRegistry();
+registry.register(createCodexProviderFactory());
+
+const client = await registry.connect({
+  profileId: profileId('codex-local'),
+  providerId: CODEX_PROVIDER_ID,
+  displayName: 'Local Codex',
+  connection: {
+    kind: 'process',
+    command: 'codex',
+    args: ['app-server', '--stdio'],
+    ownership: 'adapter',
+  },
+  requiredCapabilities: [{ name: 'input.text' }, { name: 'run.stream' }],
+});
+
+const session = await client.createSession({
+  providerOptions: {
+    approvalPolicy: 'never',
+    sandbox: 'read-only',
+    ephemeral: true,
+  },
+});
+
+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();
+  }
+}
+```
+
+## 映射与常见用法
+
+- Codex Thread 对应 Session，Turn 对应 Run；同一 Thread 同时只能有一个 Turn；
+- 文本和 Image Reference 是可移植输入，任意 File Reference 不受支持；
+- 稳定的 Command 与 File Change Request 映射为 Approval Interaction；
+- `session.ref()` 只可恢复到相同 Provider、Profile 和兼容 App Server；
+- `run.cancel()` 只有在 `turn/interrupt` 后收到权威 `interrupted`
+  终态时才算原生取消；
+- `CodexNativeClient` 可访问显式 Provider 能力，但不获得可移植生命周期保证。
+
+`turn/completed`
+是唯一权威终态。未知或畸形终态不会被猜为成功；进程退出、EOF、Client
+Close 或未确认的 Interrupt 会得到 `connection_aborted`。
+
+## 配置与安全
+
+Profile 只接受 Adapter 拥有的 `process`
+连接。可配置消息、队列、请求、取消等待和 Run
+Event 上限；未知选项会被拒绝。未消费 Event 导致 Queue 满时，Adapter 会中止连接而不是丢弃数据。
+
+错误不会包含 Provider
+Message、Prompt、文件内容、凭据、环境变量或本地路径。未知上游通知通过有界、脱敏的 Raw
+Channel 保持可观察。
+
+当前稳定 App Server 已有 Fixture、映射测试、共享 Conformance 和真实 Runtime
+Evidence。精确兼容范围、Provider Options、Live Test 和未支持能力见
+[英文详细文档](./README.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harapter/adapter-codex",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Codex App Server 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/codex#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-jsonrpc-stdio": "0.1.1"
+    "@harapter/core": "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"