agent/docs/gateway.md

Gateway: how it works

This document explains how the HTTP gateway in this repository works.

Overview

The gateway is a thin HTTP layer around @mariozechner/pi-coding-agent sessions.

Main goals:

• expose chat over HTTP (/v1/chat, /v1/chat/stream)
• keep long-lived conversation state per conversationId
• support adapter-friendly IDs (Slack/Matrix/etc.)
• optionally expose a built-in browser UI at /

Key source files:

• src/index.ts
• src/gateway/server.ts
• src/conversation-manager.ts
• src/agent-session-factory.ts
• src/gateway/events.ts

---

Startup flow

1. src/index.ts loads env config via loadConfig().
2. If RUN_MODE=single, one-shot mode is executed and exits.
3. Otherwise (RUN_MODE=gateway), it:
   • creates ConversationManager
   • initializes persisted conversation metadata (if enabled)
   • starts GatewayHttpServer
4. On SIGINT/SIGTERM, it stops the HTTP server and disposes sessions.

---

Core components

1) GatewayHttpServer (src/gateway/server.ts)

Responsible for:

• request routing
• auth and CORS handling
• request validation
• SSE streaming responses
• JSON/HTML responses

2) ConversationManager (src/conversation-manager.ts)

Responsible for:

• creating and tracking conversation records
• loading/opening/creating agent sessions
• serializing prompts per conversation (queue)
• persisting conversation index + session metadata
• aborting/deleting sessions

3) AgentSessionFactory (src/agent-session-factory.ts)

Responsible for constructing agent sessions with:

• model/provider selection (including Ollama support)
• tool selection (all, readonly, none, or subset)
• optional system prompt override/append
• auth storage and model registry wiring

---

Conversation model

A conversation is identified by conversationId.

• If client provides no ID, a UUID is generated.
• Each conversation maps to one AgentSession.
• Multiple requests for the same conversation are queued and processed in order.
• Metadata is exposed via /v1/conversations endpoints.

Validation rules:

• conversationId max length: 200
• conversationId must not contain \n/\r
• message must be a non-empty string
• images must be an array when provided
• streamingBehavior must be "steer" or "followUp" when provided

---

Persistence behavior

Controlled by SESSION_PERSIST.

SESSION_PERSIST=true

Data is stored under:

• <CWD>/.gateway/conversations.json (conversation index)
• <CWD>/.gateway/sessions/... (session files)

At startup, the index is loaded and conversations are restored as unloaded records. The actual AgentSession is lazily opened when that conversation is used.

SESSION_PERSIST=false

Everything is in memory and lost on process exit.

---

API routes

Health/UI

• GET /health → { "ok": true }
• GET / → built-in Web UI HTML (if GATEWAY_ENABLE_WEB_UI=true)

Conversation management

• GET /v1/conversations
• POST /v1/conversations
• GET /v1/conversations/:id
• DELETE /v1/conversations/:id
• POST /v1/conversations/:id/abort

Chat

• POST /v1/chat (JSON response)
• POST /v1/chat/stream (SSE response)

Adapter endpoints

• POST /v1/adapters/chat
• POST /v1/adapters/chat/stream

Adapter request fields (source, workspaceId, channelId, threadId, userId) are normalized into:

• conversationId = source:workspaceId:channelId:threadId
• adapterKey = source:workspaceId:channelId:threadId:userId

channelId is required. : is not allowed inside segment values.

For practical setup patterns per transport (Web UI, Slack, Matrix, custom), see docs/channels.md.

---

Streaming (SSE) behavior

For /v1/chat/stream and /v1/adapters/chat/stream:

1. Response starts with SSE headers.
2. A ready event is emitted.
3. Agent session events are mapped to gateway events (src/gateway/events.ts).
4. A final done event is emitted with summary payload.
5. On failure, an error event is emitted and stream ends.

Common emitted event types:

• assistant_text_delta
• assistant_thinking_delta
• assistant_message_update
• tool_start, tool_update, tool_end
• agent_start, agent_end
• retry_start, retry_end
• compaction_start, compaction_end
• done
• error

done includes:

• conversationId
• sessionId
• sessionFile
• assistantText
• plus adapterKey on adapter streaming routes

Disconnect behavior:

• if client disconnects mid-stream and the request had a conversationId, the server attempts to abort that conversation.

---

Auth and CORS

Bearer auth

If GATEWAY_AUTH_TOKEN is set, requests must include:

Authorization: Bearer <token>

Otherwise server returns 401.

Note: auth is checked before route handling, so this applies to all routes (including GET / and GET /health).

CORS

If GATEWAY_CORS_ORIGIN is set, server adds:

• Access-Control-Allow-Origin
• Access-Control-Allow-Headers: Content-Type, Authorization
• Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS

OPTIONS preflight returns 204.

---

Request limits and errors

• JSON body max size: 1 MiB (413 if exceeded)
• invalid JSON: 400
• invalid payload field types: 400
• unknown route: 404
• unexpected errors: 500

---

Environment variables (gateway-relevant)

• RUN_MODE (gateway | single)
• GATEWAY_HOST
• GATEWAY_PORT
• GATEWAY_CORS_ORIGIN
• GATEWAY_AUTH_TOKEN
• GATEWAY_ENABLE_WEB_UI
• SESSION_PERSIST
• VERBOSE_TOOLS
• CWD

See .env.example for complete defaults and comments.