xacpp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drodreo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# xacpp
+
+[中文](./README.zh-CN.md)
+
+Agent Control Plane Protocol — TypeScript implementation.
+
+xacpp defines the communication protocol between an agent and its peers. It provides a layered architecture for request-response messaging with session management over multiple transport backends.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Peer (protocol layer)                                       │
+│  Typed operations + session routing                          │
+├──────────────────────────────────────────────────────────────┤
+│  Session (session layer)                                     │
+│  Independent session context, sends directly via Transport   │
+├──────────────────────────────────────────────────────────────┤
+│  Transport (transport layer)                                 │
+│  Envelope assembly, id correlation, pending matching         │
+├──────────────────────────────────────────────────────────────┤
+│  Stdio / TCP / WebSocket                                     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+npm install xacpp
+```
+
+## Quick Start
+
+### Establish a session (initiator side)
+
+```typescript
+import { XacppPeer, XacppSession, StdioTransport, XacppSessionHandler, XacppResponse } from "xacpp";
+
+// Create transport + peer
+const transport = new StdioTransport(process.stdout, process.stdin);
+
+const peer = new XacppPeer(transport, {
+  async onEstablish(transport, credentials) {
+    return { sessionId: "server-session", handler: mySessionHandler };
+  },
+});
+
+await peer.connect();
+
+// Establish a logical session
+const session = await peer.establish(null, mySessionHandler);
+
+// Send commands/events through the session
+const response = await session.requestCommand("new_activity");
+await session.requestEvent({ type: "think", content: "Hello!" });
+```
+
+### Handle incoming requests (responder side)
+
+```typescript
+const sessionHandler: XacppSessionHandler = {
+  async onCommand(command) {
+    // Handle command
+    return { kind: "acknowledge" };
+  },
+  async onEvent(event) {
+    // Handle event
+    return { kind: "acknowledge" };
+  },
+};
+```
+
+### TCP Transport (for network communication)
+
+```typescript
+import { SocketTransport } from "xacpp";
+
+// Client
+const client = SocketTransport.connectTo(8080, "127.0.0.1");
+
+// Server (with accepted socket)
+const server = new SocketTransport(acceptedSocket);
+```
+
+## API
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `XacppTransport` | Transport interface (`connect`, `disconnect`, `send`, `onRequest`) |
+| `XacppPeer` | Protocol endpoint with session routing |
+| `XacppSession` | Logical session, sends via Transport directly |
+| `XacppSessionHandler` | Handles inbound Command/Event for a session |
+| `EstablishHandler` | Handles Establish handshake requests |
+| `XacppCommand` | Protocol commands (`establish`, `new_activity`, etc.) |
+| `XacppEvent` | Protocol events (think, action_request, question, etc.) |
+| `XacppRequest` | Request payload (`command` or `event`) |
+| `XacppResponse` | Response payload (`established`, `acknowledge`, `action`, etc.) |
+| `XacppError` | Error class with machine-readable codes |
+| `PeerState` | Peer state enum (`Disconnected`, `Connected`) |
+
+### Transports
+
+| Class | Description |
+|-------|-------------|
+| `StdioTransport` | stdin/stdout JSONL pipe |
+| `SocketTransport` | TCP socket (`net.Socket`), spawn-per-request concurrency |
+
+## Wire Protocol
+
+JSONL (one JSON object per line) with envelope structure:
+
+```json
+{"type":"request","id":"r1","payload":{"kind":"command","payload":{"establish":{"credentials":null}}}}
+{"type":"response","id":"r1","payload":{"kind":"established","sessionId":"s1"}}
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,121 @@
+# xacpp
+
+[English](./README.md)
+
+Agent Control Plane Protocol — TypeScript 实现。
+
+xacpp 定义了 Agent 与对端之间的通信协议。它提供了分层架构，支持基于请求-响应的消息传递、会话管理，以及多种传输后端。
+
+## 架构
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Peer（协议层）                                                │
+│  类型化操作 + 会话路由                                          │
+├──────────────────────────────────────────────────────────────┤
+│  Session（会话层）                                             │
+│  独立会话上下文，直达 Transport 收发                              │
+├──────────────────────────────────────────────────────────────┤
+│  Transport（传输层）                                           │
+│  信封装拆、id 关联、pending 匹配                                 │
+├──────────────────────────────────────────────────────────────┤
+│  Stdio / TCP / WebSocket                                     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## 安装
+
+```bash
+npm install xacpp
+```
+
+## 快速开始
+
+### 建立会话（发起方）
+
+```typescript
+import { XacppPeer, XacppSession, StdioTransport, XacppSessionHandler, XacppResponse } from "xacpp";
+
+// 创建 Transport + Peer
+const transport = new StdioTransport(process.stdout, process.stdin);
+
+const peer = new XacppPeer(transport, {
+  async onEstablish(transport, credentials) {
+    return { sessionId: "server-session", handler: mySessionHandler };
+  },
+});
+
+await peer.connect();
+
+// 建立逻辑会话
+const session = await peer.establish(null, mySessionHandler);
+
+// 通过会话发送命令/事件
+const response = await session.requestCommand("new_activity");
+await session.requestEvent({ type: "think", content: "Hello!" });
+```
+
+### 处理入站请求（响应方）
+
+```typescript
+const sessionHandler: XacppSessionHandler = {
+  async onCommand(command) {
+    // 处理命令
+    return { kind: "acknowledge" };
+  },
+  async onEvent(event) {
+    // 处理事件
+    return { kind: "acknowledge" };
+  },
+};
+```
+
+### TCP 传输（网络通信）
+
+```typescript
+import { SocketTransport } from "xacpp";
+
+// 客户端
+const client = SocketTransport.connectTo(8080, "127.0.0.1");
+
+// 服务端（使用已 accept 的 socket）
+const server = new SocketTransport(acceptedSocket);
+```
+
+## API
+
+### 类型
+
+| 类型 | 说明 |
+|------|------|
+| `XacppTransport` | 传输层接口（`connect`、`disconnect`、`send`、`onRequest`） |
+| `XacppPeer` | 协议端点，含会话路由 |
+| `XacppSession` | 逻辑会话，直达 Transport 收发 |
+| `XacppSessionHandler` | 处理会话内的入站 Command/Event |
+| `EstablishHandler` | 处理 Establish 握手请求 |
+| `XacppCommand` | 协议命令（`establish`、`new_activity` 等） |
+| `XacppEvent` | 协议事件（think、action_request、question 等） |
+| `XacppRequest` | 请求载荷（`command` 或 `event`） |
+| `XacppResponse` | 响应载荷（`established`、`acknowledge`、`action` 等） |
+| `XacppError` | 错误类，含机器可读错误码 |
+| `PeerState` | Peer 状态枚举（`Disconnected`、`Connected`） |
+
+### 传输实现
+
+| 类 | 说明 |
+|---|------|
+| `StdioTransport` | stdin/stdout JSONL 管道 |
+| `SocketTransport` | TCP socket（`net.Socket`），spawn-per-request 并发模型 |
+
+## 线路协议
+
+JSONL（每行一个 JSON 对象），信封结构：
+
+```json
+{"type":"request","id":"r1","payload":{"kind":"command","payload":{"establish":{"credentials":null}}}}
+{"type":"response","id":"r1","payload":{"kind":"established","sessionId":"s1"}}
+```
+
+## 许可证
+
+MIT