relmio 0.6.0 → 0.8.0

package/docs/getting-started.md

@@ -0,0 +1,38 @@
+# Getting started
+
+Relmio gives you two intentionally separate paths:
+
+| Need | Use | Credential |
+| --- | --- | --- |
+| An OpenAI-compatible local endpoint | Local OpenAI API gateway (`/v1`) | Your OpenAI Platform API key |
+| A trusted native Codex integration | Codex App Server (JSON-RPC over WebSocket) | ChatGPT sign-in and a local capability |
+| A small local chat backend | Codex Chat Adapter (`POST /chat`) | ChatGPT sign-in and a local bearer credential |
+| An n8n bridge on a VPS | The separate n8n sidecar | Your locally created ChatGPT sign-in file |
+
+ChatGPT sign-in is never converted into an OpenAI Platform API key. The Codex
+options are experimental and are not generic `/v1` services.
+
+## Install
+
+On macOS, Linux, WSL, or Git Bash, start the local wizard with:
+
+```bash
+npx --yes --ignore-scripts relmio@latest
+```
+
+The wizard prints a private loopback URL, verifies Docker before it changes
+anything, and asks for final confirmation before remote VPS writes. It binds
+local endpoints to `127.0.0.1`, never to a LAN interface.
+
+For installation options and prerequisites, see the [package
+README](https://www.npmjs.com/package/relmio). For a VPS/n8n walkthrough, see
+[VPS and n8n](./vps-and-n8n.md).
+
+## Choose the next guide
+
+- [Local endpoints](./local-endpoints.md) for the local gateway, Codex App
+  Server, or Chat Adapter.
+- [Troubleshooting](./troubleshooting.md) when Docker, authentication, or a
+  local image build stops the flow.
+- [Security](./security.md) for credential and trust boundaries.
+- [Reference](./reference.md) for test commands and protocol notes.

package/docs/images/brand/relmio-mark.svg

@@ -5,12 +5,6 @@
   aria-labelledby="relmio-mark-title"
 >
   <title id="relmio-mark-title">Relmio mark</title>
-  <path
-    fill="#137c74"
-    d="M7 8h19l31 24H41L26 20v10L7 17Z"
-  />
-  <path
-    fill="#12211f"
-    d="M7 47l19-13v10l15-12h16L26 56H7Z"
-  />
+  <path fill="#137c74" d="M8 13 28 5v38c0 4-2 7-6 9L8 59Z" />
+  <path fill="#12211f" d="M36 5l11 5c6 3 9 8 9 15v9c0 3 1 5 3 7l3 3c3 3 3 8 0 11s-8 3-11 0L40 44c-3-3-4-6-4-10Z" />
 </svg>

package/docs/local-endpoints-spec.md

@@ -112,6 +112,33 @@ say so, and the installer must reject native Windows before any write.
 Every wizard API route continues to require the existing `X-Setup-Token` and
 same-origin protections.
 
+### Chat Adapter tester APIs
+
+The tester is available only after a live `codex-chat` installation reaches the
+Ready screen. Sanitized preview mode rejects all three routes. Each route uses
+the same `POST` exact-Origin and `X-Setup-Token` protections as the rest of
+the local wizard.
+
+- `POST /api/local/chat-test/key` returns only `keyId`, an RSA public JWK,
+  `RSA-OAEP-256`, and an expiry. Its private key remains only in the local
+  server's bounded, in-memory tester-session map.
+- `POST /api/local/chat-test/message` accepts a literal loopback adapter base
+  URL, `keyId`, RSA-OAEP SHA-256 ciphertext, a bounded input, and an optional
+  bounded conversation ID. It returns only validated `conversationId` and
+  `output`.
+- `POST /api/local/chat-test/reset` invalidates the specified in-memory key.
+
+The browser sends no adapter request and stores no tester data in browser
+storage. It clears the plaintext credential input before it awaits key issuance
+or encryption, then retains ciphertext and key ID only in page memory. The
+server does not retain prompts or transcript beyond a single request.
+
+The local proxy accepts only `http://127.0.0.1:<1-65535>` with an optional
+trailing slash. It rejects DNS names, IPv6, credentials, query strings,
+fragments, paths, redirects, malformed JSON, oversized request/response data,
+expiry, and concurrent use. It appends `/chat`, uses a bounded timeout, sends
+no `Origin` header, and returns generic redacted failures.
+
 ### `GET /api/local/docker/status`
 
 Returns local Docker and Compose availability. It never returns filesystem

package/docs/local-endpoints.md

@@ -20,6 +20,16 @@ This is a documentation-backed engineering boundary, not legal advice or a
 guarantee that a particular account or use case is permitted. Review the
 agreements and policies that apply to your account.
 
+## ChatGPT/Codex sign-in lifetime
+
+ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes
+them automatically during active use before they expire, so active sessions
+usually continue without another browser login. The official [OpenAI
+authentication documentation](https://learn.chatgpt.com/docs/auth) does not
+publish a fixed 10-day lifetime; do not plan around one. This provider
+credential is separate from Relmio's local capability, which remains valid
+until you rotate it.
+
 ## Requirements
 
 - macOS, Linux, or Linux under WSL2. Native Windows is not supported because
@@ -40,7 +50,8 @@ project on the local computer.
 ## Install with the browser wizard
 
 1. Start Relmio on the computer that will run the endpoint. Use one of the
-   commands in the [README](../README.md#quick-install), or run:
+   commands on the [hosted install page](https://relmio.vercel.app/install),
+   or run:
 
    ```bash
    npx --yes --ignore-scripts relmio@latest
@@ -129,8 +140,9 @@ For a quick private test:
 
 ```bash
 export RELMIO_LOCAL_KEY="<capability shown once by the wizard>"
-curl http://127.0.0.1:12435/v1/models \
-  -H "Authorization: Bearer $RELMIO_LOCAL_KEY"
+printf 'Authorization: Bearer %s\n' "$RELMIO_LOCAL_KEY" |
+  curl http://127.0.0.1:12435/v1/models --header @-
+unset RELMIO_LOCAL_KEY
 ```
 
 The upstream key is passed only over stdin to a transient, network-disabled
@@ -179,12 +191,15 @@ official verification URL, enter the device code, and complete authentication.
 Relmio starts the login through the official Codex App Server account method;
 it never returns the resulting ChatGPT access or refresh tokens.
 
-A compatible Codex CLI can connect like this:
+A compatible Codex CLI can connect like this. Read the capability without
+putting it in the command line:
 
 ```bash
-export CODEX_REMOTE_TOKEN="<capability shown once by the wizard>"
+read -r -s CODEX_REMOTE_TOKEN
+printf '\n'
 codex --remote ws://127.0.0.1:14500 \
   --remote-auth-token-env CODEX_REMOTE_TOKEN
+unset CODEX_REMOTE_TOKEN
 ```
 
 This is not an OpenAI `/v1` endpoint. A client must implement the official
@@ -221,14 +236,19 @@ Protocol: Relmio Codex Chat HTTP
 ```
 
 After completing the same official Codex device-code sign-in, a local backend
-can start a conversation with:
+can start a conversation. Read the bearer rather than placing it in a
+shell command:
 
 ```bash
-export RELMIO_CODEX_CHAT_KEY="<capability shown once by the wizard>"
-curl http://127.0.0.1:14501/chat \
-  -H "Authorization: Bearer $RELMIO_CODEX_CHAT_KEY" \
-  -H "Content-Type: application/json" \
-  --data '{"input":"Reply with a short hello."}'
+read -r -s RELMIO_CODEX_CHAT_KEY
+printf '\n'
+printf 'Authorization: Bearer %s\n' "$RELMIO_CODEX_CHAT_KEY" |
+  curl --fail-with-body --silent --show-error \
+    --request POST http://127.0.0.1:14501/chat \
+    --header @- \
+    --header "Content-Type: application/json" \
+    --data '{"input":"Reply with a short hello."}'
+unset RELMIO_CODEX_CHAT_KEY
 ```
 
 The response contains only the App Server thread ID and final conversational
@@ -241,6 +261,24 @@ text:
 }
 ```
 
+To verify incremental delivery, request Relmio's versioned event stream. The
+stream emits `start`, `progress`, zero or more `delta` events, and exactly one
+`terminal` event. A completed terminal includes the `conversationId`; a failed
+terminal is preceded by a redacted `error` event:
+
+```bash
+read -r -s RELMIO_CODEX_CHAT_KEY
+printf '\n'
+printf 'Authorization: Bearer %s\n' "$RELMIO_CODEX_CHAT_KEY" |
+  curl --no-buffer --fail-with-body --silent --show-error \
+    --request POST http://127.0.0.1:14501/chat \
+    --header @- \
+    --header "Accept: text/event-stream" \
+    --header "Content-Type: application/json" \
+    --data '{"input":"What is a robot? Answer in two short sentences."}'
+unset RELMIO_CODEX_CHAT_KEY
+```
+
 Send that `conversationId` with the next `input` to continue the same
 conversation. The adapter initializes the official App Server, starts or
 resumes the thread, runs a read-only conversational turn, and returns the
@@ -262,6 +300,29 @@ LAN, multi-user, or production service. It enforces bounded request bodies,
 output, concurrency, process lifetime, and sanitized failures, but those
 controls do not create a general-purpose API entitlement.
 
+### In-wizard Chat Adapter tester
+
+The Ready screen for an installed Chat Adapter includes a narrow local tester.
+It is intended for a literal `http://127.0.0.1:PORT` adapter address only. The
+browser never calls the adapter: it calls the local wizard's existing
+same-origin, `X-Setup-Token` protected APIs, and the wizard makes the
+server-side `POST /chat` request without an `Origin` header.
+
+When the user secures the displayed client credential, the browser clears the
+input and encrypts it with the tester's short-lived RSA-OAEP SHA-256 public
+key. The private key exists only in local server memory, expires after a few
+minutes, has a bounded session count, and can be invalidated with **Forget
+tester**. The browser retains only ciphertext and key ID for the test session;
+it keeps prompts and transcript only in current-page memory and DOM.
+
+This reduces accidental credential transit and storage exposure. It is not
+encryption at rest or end-to-end encryption, and it cannot protect against a
+compromised browser, extension, or local machine. The tester rejects redirects,
+non-loopback URLs, malformed or oversized data, concurrent key use, and
+adapter failures with redacted messages. Assistant text appears incrementally
+while the adapter is working; the tester reports success only after the
+completed terminal event arrives.
+
 ## Network and container boundary
 
 Every local Compose project publishes exactly one host mapping:

package/docs/reference.md

@@ -0,0 +1,94 @@
+# Reference
+
+## Chat Adapter test commands
+
+The experimental Chat Adapter is a loopback-only, Relmio-specific `POST /chat`
+service for trusted local backends or development servers. It is not OpenAI
+`/v1` and it rejects browser `Origin` headers.
+
+Set the endpoint, then read the one-time credential without typing the literal
+credential into shell history:
+
+```bash
+export RELMIO_CHAT_BASE_URL="http://127.0.0.1:14501"
+read -r -s RELMIO_CHAT_CLIENT_CREDENTIAL
+printf '\n'
+```
+
+Start a conversation:
+
+```bash
+printf 'Authorization: Bearer %s\n' "$RELMIO_CHAT_CLIENT_CREDENTIAL" |
+  curl --fail-with-body --silent --show-error \
+    --request POST "$RELMIO_CHAT_BASE_URL/chat" \
+    --header @- \
+    --header "Content-Type: application/json" \
+    --data '{"input":"Reply with exactly: adapter works"}'
+```
+
+Stream a conversation and inspect its explicit terminal state:
+
+```bash
+printf 'Authorization: Bearer %s\n' "$RELMIO_CHAT_CLIENT_CREDENTIAL" |
+  curl --no-buffer --fail-with-body --silent --show-error \
+    --request POST "$RELMIO_CHAT_BASE_URL/chat" \
+    --header @- \
+    --header "Accept: text/event-stream" \
+    --header "Content-Type: application/json" \
+    --data '{"input":"What is love? Answer conversationally."}'
+```
+
+The event order is `start`, `progress`, zero or more `delta` events, then one
+`terminal`. Only `terminal: completed` is success. A failed terminal is
+preceded by a redacted `error` event and must not be treated as a partial
+answer.
+
+Copy the returned `conversationId`, then send a continuation:
+
+```bash
+export RELMIO_CONVERSATION_ID="CONVERSATION_ID_FROM_THE_PREVIOUS_RESPONSE"
+printf 'Authorization: Bearer %s\n' "$RELMIO_CHAT_CLIENT_CREDENTIAL" |
+  curl --fail-with-body --silent --show-error \
+    --request POST "$RELMIO_CHAT_BASE_URL/chat" \
+    --header @- \
+    --header "Content-Type: application/json" \
+    --data "{\"input\":\"Continue with one short sentence.\",\"conversationId\":\"$RELMIO_CONVERSATION_ID\"}"
+```
+
+Unset the shell credential when finished:
+
+```bash
+unset RELMIO_CHAT_CLIENT_CREDENTIAL
+```
+
+## Raw Codex App Server command
+
+The raw Codex App Server transport is JSON-RPC over WebSocket, experimental,
+and high-trust. It is for trusted native clients only; it is not an
+OpenAI-compatible `/v1` endpoint. Read the one-time local capability into a
+named environment variable rather than placing it in the command:
+
+```bash
+read -r -s RELMIO_CODEX_CLIENT_CREDENTIAL
+printf '\n'
+codex --remote ws://127.0.0.1:14500 \
+  --remote-auth-token-env RELMIO_CODEX_CLIENT_CREDENTIAL
+unset RELMIO_CODEX_CLIENT_CREDENTIAL
+```
+
+Keep that capability private. A trusted Codex client can control the isolated
+container and may be able to recover its ChatGPT session credential.
+
+## Local wizard tester API
+
+The browser never contacts the adapter directly. While the local wizard is
+running, its same-origin, `X-Setup-Token` protected APIs are:
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `POST` | `/api/local/chat-test/key` | Issue one ephemeral RSA-OAEP public key |
+| `POST` | `/api/local/chat-test/message` | Send encrypted credential and one bounded chat turn |
+| `POST` | `/api/local/chat-test/reset` | Invalidate the tester key and clear the browser transcript |
+
+The local proxy accepts only a literal `http://127.0.0.1:PORT` adapter base
+URL and appends `/chat` itself.

package/docs/security.md

@@ -6,6 +6,16 @@ key, a Codex/ChatGPT session, and generated local capabilities. Treat every one
 of these values as password-equivalent. Read this page before offering the
 wizard to another person.
 
+## ChatGPT/Codex sign-in lifetime
+
+ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes
+them automatically during active use before they expire, so active sessions
+usually continue without another browser login. The official [OpenAI
+authentication documentation](https://learn.chatgpt.com/docs/auth) does not
+publish a fixed 10-day lifetime; do not plan around one. This provider
+credential is separate from Relmio's local capability, which remains valid
+until you rotate it.
+
 ## Trust model
 
 The design assumes:
@@ -112,6 +122,30 @@ shared, or production service.
   resource limits; and uses root plus only `CHOWN` long enough to atomically
   make the stdin-seeded volume entry readable by the non-root gateway.
 
+### In-wizard Chat Adapter tester
+
+The Ready screen's Chat Adapter tester is a deliberately narrow convenience
+path, not a browser CORS exception. Its browser calls stay same-origin to the
+setup-token-protected wizard. Only the local wizard server calls the adapter,
+using a server-side `POST /chat` request without an `Origin` header.
+
+The tester accepts only a literal `http://127.0.0.1:PORT` base URL and appends
+`/chat` itself. It refuses `localhost`, IPv6, LAN/private/public addresses,
+credentials, query strings, fragments, redirects, malformed JSON, oversized
+payloads, excessive IDs/ciphertext, concurrent key use, and preview mode. The
+server bounds timeout and response size, validates the upstream shape, and
+returns only a conversation ID plus output with generic redacted errors.
+
+Before a test, the browser obtains an ephemeral RSA-OAEP SHA-256 public key
+from the local wizard, clears the credential input, and retains only ciphertext
+and key ID in page memory. The matching private key remains only in the local
+server's in-memory, time-limited, bounded session map and can be invalidated
+explicitly. Prompts and transcript are not persisted server-side.
+
+This is not encryption at rest or end-to-end encryption. It reduces accidental
+credential transit and storage exposure, but cannot protect a compromised
+browser, extension, or local machine.
+
 ## What “private” means here
 
 Port `10531` is not reachable from the public internet or VPS host through a

package/docs/troubleshooting.md

@@ -9,6 +9,39 @@ wizard or any manual VPS command. The documented commands are sidecar-only and
 do not delete, restart, or rebuild n8n, but they still access your VPS and write
 files there.
 
+## Docker is not running
+
+Start Docker Desktop or Docker Engine and wait until `docker info` and
+`docker compose version` both succeed. Close any stale Relmio wizard tab, start
+one fresh wizard session, and review the local plan again. Do not restart or
+rebuild unrelated containers while checking the local endpoint.
+
+## Authentication fails
+
+Close stale wizard and device-code tabs, keep the newest Relmio terminal open,
+and use only the complete wizard URL printed by that active process. Start one
+fresh ChatGPT device-code attempt and complete the newest code. A ChatGPT
+subscription credential is valid only for the Codex targets; the generic
+OpenAI-compatible `/v1` target requires a separately billed Platform API key.
+ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes
+them automatically during active use before they expire, so active sessions
+usually continue without another browser login. The official [OpenAI
+authentication documentation](https://learn.chatgpt.com/docs/auth) does not
+publish a fixed 10-day lifetime; do not plan around one. This provider
+credential is separate from Relmio's local capability, which remains valid
+until you rotate it. If Relmio reports the credential is invalid or refresh no
+longer succeeds, select **Start ChatGPT sign-in** again in the active local
+wizard. The VPS sidecar flow labels that action **Refresh ChatGPT sign-in**.
+
+## Local image build failed
+
+The local wizard intentionally does not show Docker build output, filesystem
+paths, or stderr in the browser. Confirm Docker Desktop or Docker Engine is
+running, check that the local disk has room for the image, and confirm your
+network can reach the image registry. Then close the old wizard, start one new
+wizard session, review a fresh plan, and retry. Do not delete an existing
+managed endpoint or rebuild unrelated containers as a workaround.
+
 ## Hosted chat browser extension
 
 The hosted demo at [relmio.vercel.app](https://relmio.vercel.app/) needs the

package/docs/vps-and-n8n.md

@@ -0,0 +1,30 @@
+# VPS and n8n
+
+Relmio installs a separate sidecar project at
+`/docker/n8n-openai-oauth`. It does not edit, rebuild, recreate, stop, or
+restart your existing n8n Compose project or image. The sidecar has no host
+port: n8n reaches it over the shared Docker network at
+`http://n8n-openai-oauth:10531/v1`.
+
+## Wizard route
+
+1. Run the local wizard and complete the fresh ChatGPT sign-in on your own
+   computer.
+2. Enter your VPS address and compare the presented SSH host fingerprint with
+   your provider before authorizing password authentication.
+3. Select an already-running n8n container and one of its existing shared
+   networks.
+4. Review the exact plan. Remote writes begin only after final confirmation.
+5. In n8n, use the private sidecar hostname rather than `127.0.0.1`.
+
+The n8n credential's required API-key field uses `local-only` only as a UI
+placeholder; it is not an OpenAI Platform API key.
+
+## Follow-on guides
+
+- [Configure n8n nodes](./n8n-configuration.md) has copy-ready AI Agent and
+  HTTP Request recipes.
+- [Beginner manual installation](./manual-install.md) is the auditable fallback
+  when the wizard cannot be used.
+- [Troubleshooting](./troubleshooting.md) includes connection, Docker-network,
+  and browser sign-in recovery steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relmio",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Install private local OpenAI API and Codex endpoints with explicit provider credential boundaries, plus the existing isolated n8n sidecar.",
   "keywords": [
     "relmio",

package/src/gateway/codex-chat.js

@@ -1,4 +1,4 @@
-import { createHash, timingSafeEqual } from "node:crypto";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { pathToFileURL } from "node:url";
@@ -12,6 +12,7 @@ const MAX_PROTOCOL_STDOUT_BYTES = 256 * 1024;
 const MAX_PROTOCOL_STDERR_BYTES = 64 * 1024;
 const TURN_TIMEOUT_MS = 120_000;
 const TERMINATION_GRACE_MS = 2_000;
+const KEEPALIVE_INTERVAL_MS = 15_000;
 const CONVERSATIONAL_INSTRUCTION =
   "Provide a conversational answer only. Do not inspect or edit files, run commands, call tools, or access external resources.";
 
@@ -65,6 +66,70 @@ function sendError(response, status, code) {
   sendJson(response, status, { error: { code } });
 }
 
+function acceptsEventStream(request) {
+  if (headerOccurrences(request, "accept") > 1) {
+    return false;
+  }
+  const value = request.headers.accept;
+  return (
+    typeof value === "string" &&
+    value
+      .split(",")
+      .some((entry) => entry.trim().split(";", 1)[0] === "text/event-stream")
+  );
+}
+
+function startEventStream(response, keepaliveIntervalMs) {
+  let ended = false;
+  response.writeHead(200, {
+    "Cache-Control": "no-store",
+    Connection: "keep-alive",
+    "Content-Encoding": "none",
+    "Content-Type": "text/event-stream; charset=utf-8",
+    "X-Accel-Buffering": "no",
+    "X-Content-Type-Options": "nosniff",
+    "X-Relmio-Stream": "v1",
+  });
+  const send = (event, data) => {
+    if (ended || response.writableEnded || response.destroyed) {
+      return;
+    }
+    response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  };
+  const keepalive = setInterval(() => {
+    if (!ended && !response.writableEnded && !response.destroyed) {
+      response.write(": keepalive\n\n");
+    }
+  }, keepaliveIntervalMs);
+  keepalive.unref?.();
+  send("start", { requestId: randomUUID() });
+  return {
+    send,
+    complete(result) {
+      if (ended) return;
+      send("terminal", {
+        outcome: "completed",
+        conversationId: result.conversationId,
+      });
+      ended = true;
+      clearInterval(keepalive);
+      response.end();
+    },
+    fail(code = "upstream_failed", retryable = true) {
+      if (ended) return;
+      send("error", { code, retryable });
+      send("terminal", { outcome: "failed" });
+      ended = true;
+      clearInterval(keepalive);
+      response.end();
+    },
+    dispose() {
+      ended = true;
+      clearInterval(keepalive);
+    },
+  };
+}
+
 function hasValidBearer(request, verifier) {
   if (headerOccurrences(request, "authorization") !== 1) {
     return false;
@@ -196,6 +261,8 @@ function createAppServerOperation({
   input,
   conversationId,
   packageVersion,
+  onEvent,
+  onFailure,
   signal,
   spawnProcess,
   terminationGraceMs,
@@ -241,6 +308,7 @@ function createAppServerOperation({
     let finalOutput = null;
     let latestDeltaItemId = null;
     let deltaBytes = 0;
+    let emittedDeltaBytes = 0;
     const deltaOutputs = new Map();
     let phase = "initializing";
     let outcome = null;
@@ -298,6 +366,9 @@ function createAppServerOperation({
         return;
       }
       outcome = { error, result };
+      if (error) {
+        onFailure?.(error.message === "timeout" ? "timeout" : "upstream_failed");
+      }
       signal?.removeEventListener?.("abort", abortOperation);
       clearTimeout(timeout);
       timeout = undefined;
@@ -316,6 +387,7 @@ function createAppServerOperation({
     };
     const startThread = () => {
       phase = "thread";
+      onEvent?.("progress", { phase: "starting_thread" });
       write({
         id: 1,
         method: conversationId ? "thread/resume" : "thread/start",
@@ -337,6 +409,7 @@ function createAppServerOperation({
     };
     const startTurn = () => {
       phase = "turn";
+      onEvent?.("progress", { phase: "starting_turn" });
       write({
         id: 2,
         method: "turn/start",
@@ -418,11 +491,13 @@ function createAppServerOperation({
           return;
         }
         deltaBytes += partBytes;
+        emittedDeltaBytes += partBytes;
         latestDeltaItemId = params.itemId;
         deltaOutputs.set(
           params.itemId,
           `${deltaOutputs.get(params.itemId) ?? ""}${params.delta}`,
         );
+        onEvent?.("delta", { text: params.delta });
         return;
       }
       if (message.method === "item/completed") {
@@ -468,6 +543,9 @@ function createAppServerOperation({
           failProtocol();
           return;
         }
+        if (emittedDeltaBytes === 0) {
+          onEvent?.("delta", { text: output });
+        }
         settle(null, { conversationId: threadId, output });
         return;
       }
@@ -552,6 +630,7 @@ function createAppServerOperation({
         },
       },
     });
+    onEvent?.("progress", { phase: "initializing" });
   });
 }
 
@@ -603,6 +682,7 @@ export async function startCodexChatGateway({
   spawnProcess = spawn,
   terminationGraceMs = TERMINATION_GRACE_MS,
   turnTimeoutMs = TURN_TIMEOUT_MS,
+  keepaliveIntervalMs = KEEPALIVE_INTERVAL_MS,
 } = {}) {
   if (!isLoopbackListenHost(host)) {
     throw new TypeError("Codex Chat must listen on a literal loopback-safe host.");
@@ -627,6 +707,13 @@ export async function startCodexChatGateway({
   ) {
     throw new TypeError("The Codex Chat turn timeout is invalid.");
   }
+  if (
+    !Number.isSafeInteger(keepaliveIntervalMs) ||
+    keepaliveIntervalMs < 1 ||
+    keepaliveIntervalMs > 60_000
+  ) {
+    throw new TypeError("The Codex Chat keepalive interval is invalid.");
+  }
   const verifier = validateTokenVerifier(tokenVerifier);
   const safePackageVersion = validatePackageVersion(packageVersion);
   let activeOperation = false;
@@ -673,6 +760,7 @@ export async function startCodexChatGateway({
     activeOperation = true;
     const controller = new AbortController();
     let disconnected = false;
+    let eventStream;
     const onDisconnect = () => {
       if (request.aborted || !response.writableEnded) {
         disconnected = true;
@@ -686,9 +774,16 @@ export async function startCodexChatGateway({
         if (disconnected) {
           throw new Error("unavailable");
         }
+        if (acceptsEventStream(request)) {
+          eventStream = startEventStream(response, keepaliveIntervalMs);
+        }
         return createAppServerOperation({
           ...chat,
           packageVersion: safePackageVersion,
+          onEvent: eventStream?.send,
+          onFailure: eventStream
+            ? (code) => eventStream.fail(code)
+            : undefined,
           signal: controller.signal,
           spawnProcess,
           terminationGraceMs,
@@ -697,13 +792,18 @@ export async function startCodexChatGateway({
       })
       .then((result) => {
         if (!disconnected && !response.writableEnded) {
-          sendJson(response, 200, result);
+          if (eventStream) eventStream.complete(result);
+          else sendJson(response, 200, result);
         }
       })
       .catch((error) => {
         if (disconnected || response.writableEnded) {
           return;
         }
+        if (eventStream) {
+          eventStream.fail();
+          return;
+        }
         const status = error?.status;
         const code = error?.code;
         if (status === 413 || status === 499 || code === "invalid_json" || code === "invalid_request") {
@@ -713,6 +813,7 @@ export async function startCodexChatGateway({
         sendError(response, 503, "unavailable");
       })
       .finally(() => {
+        eventStream?.dispose();
         activeOperation = false;
       });
   });