@hermit-org/stdio-to-sse 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,163 @@
+# `@hermit-org/stdio-to-sse`
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+A tiny, protocol-agnostic bridge between a stdio program and an HTTP
+POST → SSE endpoint.
+
+- **Server**: spawns a child process and exposes an HTTP endpoint. Request
+  bodies are written to the child `stdin`; child `stdout` is streamed back as
+  [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
+- **Client**: sends a POST request to such an endpoint and yields each SSE
+  payload as it arrives.
+
+No assumption is made about the message format: JSON-RPC, MCP, ACP, plain text,
+etc. are all treated as opaque byte streams.
+
+## Installation
+
+```bash
+bun add @hermit-org/stdio-to-sse
+```
+
+> Requires Node.js 18+ or [Bun](https://bun.sh/). The implementation uses
+> Node.js built-in modules only.
+
+## Running tests
+
+```bash
+cd packages/stdio-to-sse
+bun test
+```
+
+## Usage
+
+### Server
+
+```ts
+import { StdioSseServer } from "@hermit-org/stdio-to-sse";
+
+const server = new StdioSseServer({
+  command: "cat",
+  port: 8080,
+});
+
+const { url, stop } = await server.start();
+console.log(`Bridge listening on ${url}`);
+
+// Later:
+await stop();
+```
+
+### Client
+
+```ts
+import { StdioSseClient } from "@hermit-org/stdio-to-sse";
+
+const client = new StdioSseClient({ url: "http://localhost:8080" });
+
+for await (const payload of client.send("hello\nworld")) {
+  console.log(payload);
+}
+// => "hello"
+// => "world"
+```
+
+### End-to-end example
+
+```ts
+import { StdioSseServer, StdioSseClient } from "@hermit-org/stdio-to-sse";
+
+const server = new StdioSseServer({ command: "cat", port: 8080 });
+const { url, stop } = await server.start();
+
+const client = new StdioSseClient({ url });
+for await (const data of client.send("ping")) {
+  console.log(data);
+}
+
+await stop();
+```
+
+## API
+
+### `StdioSseServer`
+
+```ts
+interface StdioSseServerOptions {
+  command: string;    // command to spawn
+  args?: string[];    // command arguments
+  port?: number;      // default: 8080
+  hostname?: string;  // default: "0.0.0.0"
+  endpoint?: string;  // default: "/"
+  cors?: boolean;     // default: true
+  timeout?: number;   // max time to wait for the child process, in ms
+}
+
+class StdioSseServer {
+  constructor(options: StdioSseServerOptions);
+  start(): Promise<{ url: string; stop: () => Promise<void> }>;
+}
+```
+
+### `StdioSseClient`
+
+```ts
+interface StdioSseClientOptions {
+  url: string;
+}
+
+class StdioSseClient {
+  constructor(options: StdioSseClientOptions);
+  send(input: string): AsyncGenerator<string>;
+}
+```
+
+### SSE utilities
+
+```ts
+import { encodeSse, parseSse } from "@hermit-org/stdio-to-sse";
+
+const frame = encodeSse("hello");
+// => "data: hello\n\n"
+
+const { data, remainder } = parseSse(frame);
+// data === ["hello"]
+```
+
+## How it works
+
+1. Client sends a `POST` request to the configured endpoint.
+2. Server spawns the configured child process.
+3. Request body is written to child `stdin`, then `stdin` is closed.
+4. Server reads child `stdout`, splits it by newlines, and encodes each line
+   as an SSE `data:` frame.
+5. Client decodes the SSE stream and yields each payload.
+
+Each HTTP request gets its own child process, so requests are isolated.
+
+## Persistent gateway mode
+
+For long-lived agents (ACP / MCP / JSON-RPC sessions), use the CLI's
+`AcpGatewayServer` instead. It keeps a single child process alive and exposes
+separate SSE (`/`) and stdin (`/send`) endpoints:
+
+```ts
+import { AcpGatewayServer } from "@hermit-org/cli/src/lib/gateway";
+
+const server = new AcpGatewayServer({
+  command: "npx",
+  args: ["codex", "--acp"],
+  port: 8787,
+});
+const { url, stop } = await server.start();
+```
+
+## Notes
+
+- The child process should flush its stdout promptly; buffered output will
+  delay SSE frames.
+- `StdioSseServer` captures `stderr` but currently discards it. The CLI gateway
+  forwards `stderr` as SSE `error` frames instead.
+- Keep the bridge behind HTTPS in production; this library does not provide
+  authentication.

package/README.zh-CN.md

@@ -0,0 +1,154 @@
+# `@hermit-org/stdio-to-sse`
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+一个轻量、与协议无关的桥接库，用于将基于 stdio 的程序暴露为 HTTP POST → SSE 端点。
+
+- **服务端（Server）**：启动一个子进程并暴露 HTTP 端点。请求体会被写入子进程的 `stdin`；子进程的 `stdout` 则以 [Server-Sent Events](https://developer.mozilla.org/zh-CN/docs/Web/API/Server-sent_events) 的形式流式返回。
+- **客户端（Client）**：向该端点发送 POST 请求，并在每个 SSE 数据帧到达时实时产出。
+
+本库不对消息格式做任何假设：JSON-RPC、MCP、ACP、纯文本等都被视为不透明字节流。
+
+## 安装
+
+```bash
+bun add @hermit-org/stdio-to-sse
+```
+
+> 需要 Node.js 18+ 或 [Bun](https://bun.sh/)。实现仅使用 Node.js 内置模块。
+
+## 运行测试
+
+```bash
+cd packages/stdio-to-sse
+bun test
+```
+
+## 使用方式
+
+### 服务端
+
+```ts
+import { StdioSseServer } from "@hermit-org/stdio-to-sse";
+
+const server = new StdioSseServer({
+  command: "cat",
+  port: 8080,
+});
+
+const { url, stop } = await server.start();
+console.log(`Bridge 监听地址：${url}`);
+
+// 关闭服务：
+await stop();
+```
+
+### 客户端
+
+```ts
+import { StdioSseClient } from "@hermit-org/stdio-to-sse";
+
+const client = new StdioSseClient({ url: "http://localhost:8080" });
+
+for await (const payload of client.send("hello\nworld")) {
+  console.log(payload);
+}
+// => "hello"
+// => "world"
+```
+
+### 端到端示例
+
+```ts
+import { StdioSseServer, StdioSseClient } from "@hermit-org/stdio-to-sse";
+
+const server = new StdioSseServer({ command: "cat", port: 8080 });
+const { url, stop } = await server.start();
+
+const client = new StdioSseClient({ url });
+for await (const data of client.send("ping")) {
+  console.log(data);
+}
+
+await stop();
+```
+
+## API 说明
+
+### `StdioSseServer`
+
+```ts
+interface StdioSseServerOptions {
+  command: string;    // 要启动的命令
+  args?: string[];    // 命令参数
+  port?: number;      // 默认：8080
+  hostname?: string;  // 默认："0.0.0.0"
+  endpoint?: string;  // 默认："/"
+  cors?: boolean;     // 默认：true
+  timeout?: number;   // 子进程最长运行时间（毫秒）
+}
+
+class StdioSseServer {
+  constructor(options: StdioSseServerOptions);
+  start(): Promise<{ url: string; stop: () => Promise<void> }>;
+}
+```
+
+### `StdioSseClient`
+
+```ts
+interface StdioSseClientOptions {
+  url: string;
+}
+
+class StdioSseClient {
+  constructor(options: StdioSseClientOptions);
+  send(input: string): AsyncGenerator<string>;
+}
+```
+
+### SSE 工具函数
+
+```ts
+import { encodeSse, parseSse } from "@hermit-org/stdio-to-sse";
+
+const frame = encodeSse("hello");
+// => "data: hello\n\n"
+
+const { data, remainder } = parseSse(frame);
+// data === ["hello"]
+```
+
+## 工作原理
+
+1. 客户端向配置的端点发送 `POST` 请求。
+2. 服务端启动配置好的子进程。
+3. 请求体被写入子进程的 `stdin`，随后 `stdin` 被关闭。
+4. 服务端读取子进程的 `stdout`，按换行拆分，并将每一行编码为 SSE `data:` 帧。
+5. 客户端解码 SSE 流并逐帧产出数据内容。
+
+每个 HTTP 请求都会独立启动一个子进程，因此请求之间是相互隔离的。
+
+## 持久化 Gateway 模式
+
+如果需要长期运行的 Agent（ACP / MCP / JSON-RPC 会话），请使用 CLI 提供的
+`AcpGatewayServer`。它会保持一个子进程长期存活，并分别暴露 SSE（`/`）和 stdin
+（`/send`）端点：
+
+```ts
+import { AcpGatewayServer } from "@hermit-org/cli/src/lib/gateway";
+
+const server = new AcpGatewayServer({
+  command: "npx",
+  args: ["codex", "--acp"],
+  port: 8787,
+});
+const { url, stop } = await server.start();
+```
+
+## 注意事项
+
+- 子进程应及时刷新 stdout；缓冲输出会延迟 SSE 帧的到达。
+- `StdioSseServer` 会捕获 `stderr` 但直接丢弃。CLI 的 Gateway 则会将 `stderr`
+  作为 SSE `error` 帧转发。
+- 生产环境中请将该桥接服务置于 HTTPS 之后；本库不提供身份验证功能。

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@hermit-org/stdio-to-sse",
+  "version": "0.0.1-alpha.0",
+  "type": "module",
+  "module": "src/index.ts",
+  "react-native": "./src/index.native.ts",
+  "browser": "./src/index.native.ts",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "browser": "./src/index.native.ts",
+      "default": "./src/index.ts"
+    },
+    "./client": "./src/client.ts",
+    "./server": "./src/server.ts"
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,191 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { createServer, type Server } from "node:http";
+import { StdioSseClient } from "./index";
+
+function startSseServer(
+  handler: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => void,
+): Promise<{ url: string; server: Server; stop: () => Promise<void> }> {
+  return new Promise((resolve, reject) => {
+    const server = createServer(handler);
+
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.removeListener("error", reject);
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : 0;
+      resolve({
+        url: `http://127.0.0.1:${port}`,
+        server,
+        stop: () => new Promise((resolveStop) => server.close(() => resolveStop())),
+      });
+    });
+  });
+}
+
+async function readRequestBody(req: import("node:http").IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+describe("StdioSseClient", () => {
+  test("yields a single SSE data payload", async () => {
+    const { url, stop } = await startSseServer(async (req, res) => {
+      const body = await readRequestBody(req);
+      expect(body).toBe("ping");
+
+      res.writeHead(200, { "Content-Type": "text/event-stream" });
+      res.write("data: hello\n\n");
+      res.end();
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("ping")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["hello"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("yields multiple SSE data payloads", async () => {
+    const { url, stop } = await startSseServer(async (_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/event-stream" });
+      res.write("data: one\n\ndata: two\n\n");
+      res.end();
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["one", "two"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("handles an SSE frame split across multiple chunks", async () => {
+    const { url, stop } = await startSseServer(async (_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/event-stream" });
+      res.write("data: hel");
+      res.write("lo\n\n");
+      res.end();
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["hello"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("reconstructs multi-line SSE payloads", async () => {
+    const { url, stop } = await startSseServer(async (_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/event-stream" });
+      res.write("data: line1\ndata: line2\n\n");
+      res.end();
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["line1\nline2"]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("handles an empty response body gracefully", async () => {
+    const { url, stop } = await startSseServer(async (_req, res) => {
+      res.writeHead(200);
+      res.end();
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual([]);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("throws when the server returns a non-2xx status", async () => {
+    const { url, stop } = await startSseServer(async (_req, res) => {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("not found");
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const iterator = client.send("");
+
+      await expect(iterator.next()).rejects.toThrow("HTTP error 404");
+    } finally {
+      await stop();
+    }
+  });
+
+  test("propagates network errors", async () => {
+    const client = new StdioSseClient({
+      url: "http://127.0.0.1:1",
+    });
+
+    await expect(async () => {
+      for await (const _ of client.send("")) {
+        // consume
+      }
+    }).toThrow();
+  });
+
+  test("accepts responses with non-SSE Content-Type", async () => {
+    const { url, stop } = await startSseServer(async (_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.write("data: still-parsed\n\n");
+      res.end();
+    });
+
+    try {
+      const client = new StdioSseClient({ url });
+      const results: string[] = [];
+
+      for await (const data of client.send("")) {
+        results.push(data);
+      }
+
+      expect(results).toEqual(["still-parsed"]);
+    } finally {
+      await stop();
+    }
+  });
+});

package/src/client.ts

@@ -0,0 +1,140 @@
+import { parseSse } from "./sse";
+
+/**
+ * Configuration for `StdioSseClient`.
+ */
+export interface StdioSseClientOptions {
+  /** URL of the stdio-to-sse HTTP endpoint. */
+  url: string;
+  /** Optional headers to send with the POST request. */
+  headers?: Record<string, string>;
+  /**
+   * Maximum number of reconnection attempts when the stream drops unexpectedly
+   * (default: `0`). Each `send()` call is independent; reconnection only
+   * applies within a single call.
+   */
+  maxRetries?: number;
+  /**
+   * Initial backoff delay in milliseconds between retries (default: `1000`).
+   * Delays double on each attempt up to `maxRetryDelay`.
+   */
+  retryDelay?: number;
+  /** Maximum backoff delay in milliseconds (default: `30000`). */
+  maxRetryDelay?: number;
+}
+
+/**
+ * HTTP client that sends a request body to a stdio-to-sse server and yields
+ * each SSE payload as it arrives.
+ *
+ * Like the server, this client is protocol-agnostic: it only understands the
+ * SSE framing and returns the raw `data:` contents. It adds transport-level
+ * resilience through optional retries with exponential backoff.
+ */
+export class StdioSseClient {
+  constructor(private readonly options: StdioSseClientOptions) {}
+
+  /**
+   * Send input to the server and asynchronously yield each SSE payload.
+   *
+   * @param input Text to write to the child process stdin.
+   * @yields Raw payloads received from the SSE stream.
+   */
+  async *send(input: string): AsyncGenerator<string> {
+    const {
+      url,
+      headers = {},
+      maxRetries = 0,
+      retryDelay = 1000,
+      maxRetryDelay = 30000,
+    } = this.options;
+
+    let attempt = 0;
+    let lastError: Error | undefined;
+
+    while (attempt <= maxRetries) {
+      try {
+        for await (const item of this.sendOnce(input, headers)) {
+          yield item;
+        }
+        return;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt >= maxRetries) break;
+
+        const delay = Math.min(retryDelay * 2 ** attempt, maxRetryDelay);
+        await sleep(delay);
+        attempt++;
+      }
+    }
+
+    throw lastError ?? new Error("SSE request failed");
+  }
+
+  private async *sendOnce(
+    input: string,
+    headers: Record<string, string>,
+  ): AsyncGenerator<string> {
+    const response = await fetch(this.options.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "text/plain",
+        Accept: "text/event-stream",
+        ...headers,
+      },
+      body: input,
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(
+        `HTTP error ${response.status}: ${text || response.statusText}`,
+      );
+    }
+
+    // React Native's fetch polyfill does not expose a streaming response body,
+    // and some environments may not have a global TextDecoder. Fall back to
+    // reading the whole response as text and then parsing the SSE frames.
+    if (!response.body || typeof TextDecoder === "undefined") {
+      const text = await response.text();
+      const { data } = parseSse(text);
+      for (const item of data) {
+        yield item;
+      }
+      return;
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // Parse complete frames and keep unfinished bytes for the next chunk.
+        const { data, remainder } = parseSse(buffer);
+        buffer = remainder;
+
+        for (const item of data) {
+          yield item;
+        }
+      }
+
+      // Flush any trailing data after the stream ends.
+      const { data } = parseSse(buffer);
+      for (const item of data) {
+        yield item;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/index.native.ts

@@ -0,0 +1,11 @@
+/**
+ * React Native entry point for `@hermit-org/stdio-to-sse`.
+ *
+ * Metro's platform-specific extension resolution will prefer `.native.ts`
+ * over `.ts` when bundling for React Native. This entry re-exports only the
+ * client and the protocol utilities, avoiding Node.js built-in modules that
+ * the server implementation depends on.
+ */
+
+export * from "./sse";
+export * from "./client";

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Public API entry point for `@hermit-org/stdio-to-sse`.
+ *
+ * This package bridges a stdio-based program to an HTTP POST -> SSE endpoint.
+ * It exposes a server that spawns a child process and streams its stdout as
+ * Server-Sent Events, plus a client that consumes those events.
+ *
+ * The implementation uses Node.js built-in modules, so it runs under both
+ * Node.js (18+) and Bun.
+ *
+ * Types are defined alongside their implementations rather than in a central
+ * types file, so exports are re-exported per module below.
+ */
+
+export * from "./sse";
+export * from "./server";
+export * from "./client";