koel_http library

HTTP/SSE transport for AG-UI agents — HttpAgent, SseParser, interceptors.

Classes

AuthInterceptor

Authenticates every run by composing an interceptor instead of configuring the agent (FR-B2). Takes an async header-builder — a closure that can mint a Bearer token, read a keychain, or refresh on demand — resolves it per run (or per retry attempt, see below), and threads the resolved headers onto the outgoing POST.

EventTraceInterceptor

Captures a structured TraceEntry for every event flowing through a run and writes it to a consumer-supplied Sink<TraceEntry> (Story 4.6 / FR-B2).

HttpAgent

AbstractAgent over an AG-UI SSE endpoint — the first koel transport that talks to a network (FR-B1, AR-7).

LoggingInterceptor

Writes human-readable run logs to package:logging at the architecture-§4 per-category levels, gated by a single emission level threshold (Story 4.6 / FR-B2/B3). The human-readable complement to EventTraceInterceptor's structured TraceEntry capture; compose whichever (or both) into HttpAgent(interceptors: …).

PIIRedactionInterceptor

Scrubs consumer-supplied patterns out of the free-text content an AgUiEvent carries, replacing every match with [REDACTED] before the event reaches subscribers or the reducer (Story 4.7 / FR-I2). Default-OFF — it does nothing unless a consumer adds it to HttpAgent(interceptors: …).

RetryInterceptor

Re-runs a failed run with exponential backoff + jitter, emitting a ConnectionResumed marker on a recovered reconnect and a terminal TransportError(transportClosed) on exhaustion (FR-B4 / NFR-7).

RetryPolicy

Declarative retry/backoff configuration for an HttpAgent reconnection — the convenience entry point to the RetryInterceptor engine (Story 4.4).

SentryBreadcrumbInterceptor

Adds one Sentry breadcrumb per AgUiEvent flowing through a run, so a consumer's later-captured Sentry errors carry the AG-UI run trail that led to them (Story 4.7 / FR-I2). Default-OFF — it is never in HttpAgent's default chain and emits nothing unless a consumer (a) adds it to HttpAgent(interceptors: …) and (b) has called Sentry.init in their app. Even then, breadcrumbs only leave the device when an actual Sentry event is captured: this interceptor generates no standalone network traffic, so "no silent telemetry" holds.

SseParser

The wire→domain boundary of koel_http: a hand-rolled, dependency-free SSE parser that turns a raw byte stream into a typed AgUiEvent stream (AR-8).

TraceEntry

A single structured observation of a run, written to a consumer's Sink<TraceEntry> by the EventTraceInterceptor (Story 4.6 / FR-B2).

Enums

TracePhase

Where in a run's lifecycle a TraceEntry was captured.

Extensions

TraceEntryPatterns on TraceEntry

Adds pattern-matching-related methods to TraceEntry.

Functions

retryBackoff(int attempt, {required Duration baseDelay, required Duration maxDelay, required double jitter, required Random random}) → Duration

The pure, deterministic backoff schedule: min(maxDelay, baseDelay·2^(n-1)) scaled by a symmetric jitter factor in [1−jitter, 1+jitter). attempt is 1-based; random is injected so a seeded Random makes tests deterministic.

transportErrorClassifier() → ErrorClassifier

The koel_http transport ErrorClassifier, resolved per platform at compile time — the seam HttpAgent.run builds its InterceptorChain over.