Safe Haskell	None
Language	GHC2024

Free.Agent.Gateway

Contents

Configuration
Client
Turns
Host seat
SSE framing (exposed for pure tests)

Description

Hermes gateway api_server client: one persistent server-side session as a Host seat.

The api_server (part of hermes gateway run) offers POST /api/sessions and POST /api/sessions/{id}/chat/stream — SSE event streams with protocol-posted halt marks (run.completed, done). Framing is the frameAgent mark machine at sseMarks: the blank line ends an event frame, the event names are the halt alphabet. No polling, no quiet inference — the server posts its own marks.

Auth is a Bearer token read from the environment variable named by gwKeyEnv (default API_SERVER_KEY, the platform's own convention).

Probe card: coffee/loom/next-yin.md ("hermes server (api_server :8642)").

Synopsis

data GatewayConfig = GatewayConfig {
- gwBaseUrl :: Text
- gwKeyEnv :: String
- gwCwd :: FilePath
}
defaultGatewayConfig :: GatewayConfig
data GatewayClient = GatewayClient {
- gcConfig :: GatewayConfig
- gcManager :: Manager
- gcKey :: ByteString
- gcSessionId :: Text
}
openGateway :: GatewayConfig -> IO GatewayClient
gatewayChat :: GatewayClient -> Text -> IO Text
gatewayHost :: Text -> Text -> GatewayClient -> Host
parseSseFrame :: ByteString -> Maybe (Text, Json)

Configuration

data GatewayConfig Source #

Where the api_server is and how to authenticate to it.

Constructors

GatewayConfig
Fields gwBaseUrl :: Text Base URL, e.g. `http://127.0.0.1:8642`. gwKeyEnv :: String Environment variable holding the Bearer key. gwCwd :: FilePath Working directory pinned on the server-side session.

Instances

Instances details

Eq GatewayConfig Source #
Instance details Defined in Free.Agent.Gateway Methods (==) :: GatewayConfig -> GatewayConfig -> Bool # (/=) :: GatewayConfig -> GatewayConfig -> Bool #
Show GatewayConfig Source #
Instance details Defined in Free.Agent.Gateway Methods showsPrec :: Int -> GatewayConfig -> ShowS # show :: GatewayConfig -> String # showList :: [GatewayConfig] -> ShowS #

defaultGatewayConfig :: GatewayConfig Source #

Client

data GatewayClient Source #

A live api_server session.

Constructors

GatewayClient
Fields gcConfig :: GatewayConfig gcManager :: Manager gcKey :: ByteString gcSessionId :: Text

openGateway :: GatewayConfig -> IO GatewayClient Source #

Read the Bearer key from gwKeyEnv and create a server-side session.

Turns

gatewayChat :: GatewayClient -> Text -> IO Text Source #

One turn: POST chat/stream, consume SSE events until the done mark, return the completed reply text.

The reply is the assistant.completed content when it arrives, else the accumulated assistant.delta stream. HTTP and stream failures come back as 🔴-prefixed text (the chatCompletion convention), so a failing gateway surfaces as a bus post, not a crash.

Host seat

gatewayHost Source #

Arguments

:: Text	Host name (used as the `from` field of reply posts).
-> Text	System prompt text prepended to every message.
-> GatewayClient
-> Host

A Host backed by the gateway session. All post bodies of a wake cycle join into one user message (the hermesHostBatch convention); the reply is one text.

SSE framing (exposed for pure tests)

parseSseFrame :: ByteString -> Maybe (Text, Json) Source #

Parse one SSE event frame (event: x\ndata: {…}) into the event name and decoded JSON payload. Nothing for comment/keep-alive frames.

>>> parseSseFrame (Data.ByteString.Char8.pack "event: done\ndata: {\"seq\": 7}")
Just ("done",JObject [("seq",JNumber 7.0)])