@rein-ai/server

Rein server with artifact persistence (SQLite) and SSE streaming for all connections.

Programmatic API

import { createServer } from "@rein-ai/server";

const server = await createServer({ port: 4800 });
// server.port — actual port (useful if port: 0 was passed)
// server.store — SessionStore instance
// server.createSession(id, project?) — create a session
// server.getSession(id) — get a session by ID
// server.getSessions({ project? }) — list sessions
// server.close() — stop the server

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | port | number | 0 | Port to listen on (0 = OS-assigned) | | bootstrapTimeout | number | 180000 | Ms before bootstrapping sessions are removed | | store | SessionStore | SQLite | Custom store implementation | | dbPath | string | in-memory | Path to SQLite database file |

HTTP Routes

Sessions

| Method | Path | Description | |--------|------|-------------| | GET | /sessions | List all sessions | | GET | /sessions?project=x | List sessions filtered by project | | GET | /sessions/:id | Get a single session | | POST | /sessions/:id | Create a session | | DELETE | /sessions/:id | Remove a session |

Session record:

{
  "id": "uuid",
  "status": "bootstrapping | live | idle | disconnected",
  "summary": "string | null",
  "project": "string | null",
  "createdAt": 1234567890,
  "lastHeartbeat": 1234567890
}

Commands

| Method | Path | Description | |--------|------|-------------| | POST | /sessions/:id/commands | Send a command to the sandbox |

Command body:

{ "type": "prompt", "text": "fix the bug" }
{ "type": "abort" }

Returns 202 on success, 409 if no sandbox is connected, 404 if session not found.

Events (from sandbox)

| Method | Path | Description | |--------|------|-------------| | POST | /sessions/:id/events | Sandbox posts a ReinEvent |

Event body: Any valid ReinEvent JSON (e.g. { "type": "text_delta", "delta": "..." }).

Returns 202 on success, 404 if session not found. Events are processed through the reducer and published as artifact updates to SSE clients.

Artifacts

| Method | Path | Description | |--------|------|-------------| | GET | /sessions/:id/artifacts | Get all artifacts for a session |

Returns a JSON array of artifact objects ordered by sequence number.

SSE Endpoints

Artifact stream — GET /sessions/:id/stream

Streams artifact events for a single session. On connect, sends the full artifact history as snapshots, then live events.

Reconnection: Send Last-Event-ID header with the last received sequence number. The server resends artifacts from that point.

Events:

| Event | When | Data | |-------|------|------| | artifact_snapshot | On connect (history replay) | { artifact: Artifact } | | artifact_created | New artifact | { artifact: Artifact } | | artifact_updated | Artifact field changed | { seq, field, append?, set? } |

Each event includes an id field set to the artifact's sequence number.

Session stream — GET /sessions/stream

Streams session-level state changes. On connect, sends all current sessions as snapshots, then live events.

Filtering: Add ?project=x to only receive events for sessions matching that project.

Events:

| Event | When | Data | |-------|------|------| | session_snapshot | On connect (one per session) | { session: SessionRecord } | | session_created | New session created | { session: SessionRecord } | | session_updated | Status or summary changed | { id, fields: { status?, summary? } } | | session_removed | Session deleted or timed out | { id } |

Heartbeat-only updates are not broadcast.

Command stream — GET /sessions/:id/commands

SSE endpoint for sandbox (agent) connections. Opening this stream marks the session as "live". Commands sent by clients via POST /sessions/:id/commands are delivered here.

Events:

| Event | When | Data | |-------|------|------| | command | Client sends a command | { type: "prompt", text: "..." } or { type: "abort" } |

Connection lifecycle:

• Connect: session status → "live"
• Disconnect: session status → "disconnected" (if was "live" or "idle")
• If a new sandbox connects while one exists, the old connection is closed

Architecture

Clients (CLI, web)          Sandbox (agent)
      │                           │
      │ SSE + POST                │ SSE + POST
      │                           │
      ▼                           ▼
┌──────────────────────────────────────┐
│              Server                  │
│                                      │
│  HTTP routes    SSE streams          │
│  Reducer        Persistence          │
│                                      │
│         SessionStore (SQLite)        │
│         EventEmitter (pub/sub)       │
└──────────────────────────────────────┘