@briancray/belte 0.3.1 → 0.4.0

package/src/lib/server/runtime/globToPathSet.ts

@@ -0,0 +1,29 @@
+import { Glob } from 'bun'
+
+/*
+Scans `cwd` for files matching `pattern` and returns their request paths as
+a Set, mapping each relative file path to a root-relative URL via `keyFor`.
+Used to snapshot the on-disk asset trees (the `public/` files, the `_app`
+precompressed `.zst` siblings) once at boot so the request path is a Set
+lookup instead of a filesystem stat.
+
+A missing directory makes scan throw ENOENT — swallowed to an empty Set so
+the caller just falls through. This scan-and-catch is also the reliable
+directory existence test: `Bun.file(dir).exists()` returns false for a
+directory, so guarding the scan with it silently yields an empty Set.
+*/
+export async function globToPathSet(
+    cwd: string,
+    pattern: string,
+    keyFor: (file: string) => string,
+    options?: { dot?: boolean },
+): Promise<Set<string>> {
+    try {
+        const files = await Array.fromAsync(
+            new Glob(pattern).scan({ cwd, dot: options?.dot ?? false }),
+        )
+        return new Set(files.map(keyFor))
+    } catch {
+        return new Set()
+    }
+}

package/src/lib/server/runtime/logBrowserOnlyRoutes.ts

@@ -0,0 +1,44 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { log } from '../../shared/log.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { socketRegistry } from '../sockets/socketRegistry.ts'
+import { ensureRegistriesLoaded } from './registryManifests.ts'
+
+/*
+Surfaces the otherwise-silent consequence of belte's multimodal-by-default
+rule: a verb or socket with no schema never reaches MCP or the CLI, since
+the schema is what makes those surfaces safe to advertise. Loads the full
+registry, then logs (once at boot, only when `belte` debug logging is on
+so it doesn't force eager imports in production) the routes that stay
+browser-only purely for lack of a schema — so the missing matrix cells
+are visible rather than surprising. Best-effort: enumeration failures are
+swallowed since this is diagnostic only.
+*/
+export async function logBrowserOnlyRoutes(): Promise<void> {
+    try {
+        await ensureRegistriesLoaded()
+    } catch {
+        return
+    }
+    const names: string[] = []
+    for (const entry of verbRegistry.values()) {
+        if (
+            entry.clients.browser &&
+            !entry.clients.mcp &&
+            !entry.clients.cli &&
+            !entry.inputSchema
+        ) {
+            names.push(commandNameForUrl(entry.remote.url))
+        }
+    }
+    for (const entry of socketRegistry.values()) {
+        if (entry.clients.browser && !entry.clients.mcp && !entry.clients.cli && !entry.schema) {
+            names.push(entry.socket.name)
+        }
+    }
+    if (names.length > 0) {
+        log.detail(
+            `browser-only (no schema → not on MCP/CLI): ${names.sort().join(', ')} — add a schema to expose them`,
+        )
+    }
+}

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,6 +1,10 @@
 import type { ServerWebSocket } from 'bun'
 import { log } from '../../shared/log.ts'
+import { error } from '../error.ts'
+import { json } from '../json.ts'
+import { sse } from '../sse.ts'
 import { lookupSocket } from './lookupSocket.ts'
+import { recentHistory } from './recentHistory.ts'
 import type { SocketClientFrame } from './types/SocketClientFrame.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
 import type { SocketServerFrame } from './types/SocketServerFrame.ts'
@@ -12,6 +16,7 @@ type SocketDispatcher = {
     open(ws: ServerWebSocket<unknown>): void
     message(ws: ServerWebSocket<unknown>, data: string | Buffer): void
     close(ws: ServerWebSocket<unknown>): void
+    rest(req: Request, name: string): Promise<Response>
 }
 
 /*
@@ -154,14 +159,9 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         a number is clamped to the buffer length so the client can ask
         for "as many as available, up to N".
         */
-        const history = entry.snapshotHistory()
-        const replayCount =
-            frame.replay === undefined ? history.length : Math.min(frame.replay, history.length)
-        if (replayCount > 0) {
-            history.slice(history.length - replayCount).forEach((message) => {
-                send(ws, { type: 'msg', socket: frame.socket, message })
-            })
-        }
+        recentHistory(entry, frame.replay).forEach((message) => {
+            send(ws, { type: 'msg', socket: frame.socket, message })
+        })
     }
 
     function handleUnsub(
@@ -225,7 +225,70 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         void ws
     }
 
+    /*
+    HTTP face of the sockets hub at `/__belte/sockets/<name>`, for the CLI
+    and MCP (which can't speak the ws multiplex protocol):
+
+      GET  text/event-stream → live SSE stream; `?tail=N` replays the last
+           N buffered messages before tailing live (default 0 = live only).
+      GET  otherwise         → JSON array of the recent history buffer
+           (`?tail=N` caps it; default all).
+      POST                   → publish the JSON body, gated by the socket's
+           clientPublish policy and validated against its schema.
+
+    Loads the socket module on first hit (same cache the ws path uses) so
+    its defineSocket call populates the registry.
+    */
+    async function rest(req: Request, name: string): Promise<Response> {
+        const loader = ensureLoaded(name)
+        if (!loader) {
+            return error(404)
+        }
+        try {
+            await loader
+        } catch (loadError) {
+            log.error(loadError)
+            return error(500, 'socket failed to load')
+        }
+        const entry = lookupSocket(name)
+        if (!entry) {
+            return error(404)
+        }
+        const tailParam = new URL(req.url).searchParams.get('tail')
+        const count = tailParam !== null ? Number(tailParam) : undefined
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            if ((req.headers.get('accept') ?? '').includes('text/event-stream')) {
+                return sse(entry.socket.tail(count ?? 0))
+            }
+            return json(recentHistory(entry, count))
+        }
+        if (req.method === 'POST') {
+            if (!entry.allowClientPublish) {
+                return error(403, 'publishing not allowed')
+            }
+            let message: unknown
+            try {
+                message = await req.json()
+            } catch {
+                return error(400, 'body must be JSON')
+            }
+            try {
+                // publish() validates against the socket schema and throws on a bad payload.
+                entry.socket.publish(message)
+            } catch (publishError) {
+                return error(
+                    422,
+                    publishError instanceof Error ? publishError.message : String(publishError),
+                )
+            }
+            return json({ ok: true })
+        }
+        return error(405, undefined, { headers: { Allow: 'GET, POST' } })
+    }
+
     return {
+        rest,
+
         open(ws) {
             connections.set(ws, { subToSocket: new Map(), socketSubs: new Map() })
         },

package/src/lib/server/sockets/defineSocket.ts

@@ -29,7 +29,13 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
     const ttl = opts.ttl
     const schema = opts.schema
     const jsonSchema = opts.jsonSchema
-    const clients = resolveClientFlags(opts.clients, schema !== undefined)
+    /*
+    A schema makes the socket's payload safe to advertise to non-browser
+    surfaces, so it flips mcp/cli on by default — exposing the `tail` read
+    tool (and `publish` when clientPublish is set). Explicit `clients` wins.
+    */
+    const hasSchema = schema !== undefined
+    const clients = resolveClientFlags(opts.clients, { mcp: hasSchema, cli: hasSchema })
     type BufferEntry = { value: T; expiresAt: number | undefined }
     const buffer: BufferEntry[] = []
     const subscribers = new Set<(message: T) => void>()

package/src/lib/server/sockets/recentHistory.ts

@@ -0,0 +1,11 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Recent slice of a socket's history buffer: the last `count` messages, or
+the whole buffer when `count` is undefined. Shared by the sockets HTTP
+`rest()` face and the MCP `<base>-tail` tool so the two can't drift.
+*/
+export function recentHistory(entry: SocketRegistryEntry, count: number | undefined): unknown[] {
+    const history = entry.snapshotHistory()
+    return count === undefined ? history : history.slice(Math.max(0, history.length - count))
+}

package/src/lib/server/sockets/socketOperations.ts

@@ -0,0 +1,35 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import type { SocketOperation } from './types/SocketOperation.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Projects a socket registry entry into the operations it exposes to the
+CLI and MCP. Single source for the naming convention (`<base>-tail` /
+`<base>-publish`), the existence rule (tail always; publish only when the
+socket allows client publishing), and each operation's HTTP face — so the
+CLI manifest builder, the MCP tool list, and the MCP tool dispatcher can't
+disagree about which operations a socket has or what they're called.
+*/
+export function socketOperations(entry: SocketRegistryEntry): SocketOperation[] {
+    const base = commandNameForUrl(entry.socket.name)
+    const restUrl = `/__belte/sockets/${entry.socket.name}`
+    const operations: SocketOperation[] = [
+        {
+            kind: 'tail',
+            name: `${base}-tail`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'GET',
+        },
+    ]
+    if (entry.allowClientPublish) {
+        operations.push({
+            kind: 'publish',
+            name: `${base}-publish`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'POST',
+        })
+    }
+    return operations
+}

package/src/lib/server/sockets/types/SocketOperation.ts

@@ -0,0 +1,22 @@
+import type { HttpVerb } from '../../rpc/types/HttpVerb.ts'
+
+/*
+One operation a socket exposes to the non-browser surfaces. A socket
+always offers a `tail` (read recent / stream live) and, when
+`clientPublish` is set, a `publish` (send a message). This is the shared
+skeleton — name, kind, HTTP face — that the CLI manifest, the MCP tool
+list, and the MCP dispatcher all read instead of re-deriving the naming
+convention and existence rule independently. Each surface dresses it with
+its own presentation (descriptions, input schema, annotations).
+*/
+export type SocketOperation = {
+    kind: 'tail' | 'publish'
+    // Command/tool name: the socket's command-name base plus `-tail` / `-publish`.
+    name: string
+    // Raw socket name, for the HTTP path and human-facing descriptions.
+    socketName: string
+    // HTTP face of the operation: `/__belte/sockets/<name>`.
+    restUrl: string
+    // GET for tail, POST for publish.
+    method: HttpVerb
+}

package/src/lib/server/sse.ts

@@ -24,6 +24,7 @@ EventSource surfaces this via its `error` listener and `subscribe()`
 maps it to the entry's `error` field.
 */
 import { NO_STORE } from '../shared/cacheControlValues.ts'
+import { sseErrorFrame } from '../shared/sseErrorFrame.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
 import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
@@ -36,7 +37,7 @@ export function sse<Frame>(
 ): TypedResponse<Frame> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
-        encodeError: (message) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`,
+        encodeError: (message) => sseErrorFrame.encode(message),
         keepaliveMs: KEEPALIVE_INTERVAL_MS,
         keepalivePayload: ': keepalive\n\n',
     })

package/src/lib/shared/buildRpcRequest.ts

@@ -1,4 +1,5 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
 
 /*
 Builds the Request a verb helper uses to invoke its handler. Same shape on
@@ -27,7 +28,7 @@ export function buildRpcRequest({
     headers?: Headers
 }): Request {
     const requestHeaders = headers ?? new Headers()
-    if (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
+    if (!carriesBodyArgs(method)) {
         const target = appendQuery(method, url, args)
         return new Request(new URL(target, baseUrl).href, { method, headers: requestHeaders })
     }

package/src/lib/shared/carriesBodyArgs.ts

@@ -0,0 +1,13 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+
+/*
+Whether a verb carries its args in the request body (POST/PUT/PATCH) vs
+on the query string (GET/DELETE/HEAD). Single source for the split so the
+synthesized Request (buildRpcRequest), the handler-side parse (parseArgs),
+the cache key (keyForRemoteCall), and the OpenAPI doc can't disagree.
+*/
+const BODY_METHODS = new Set<HttpVerb>(['POST', 'PUT', 'PATCH'])
+
+export function carriesBodyArgs(method: HttpVerb): boolean {
+    return BODY_METHODS.has(method)
+}

package/src/lib/shared/isReadOnlyMethod.ts

@@ -0,0 +1,14 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+
+/*
+Read-only (safe) HTTP methods — they don't mutate server state. Belte
+uses this to decide which verbs auto-expose to MCP: reads flip MCP on
+when a schema is present, mutations require an explicit `clients.mcp`
+opt-in so a model can't delete/overwrite data just because the handler
+carries a schema. Also feeds the MCP tool `readOnlyHint` annotation.
+*/
+const READ_ONLY_METHODS = new Set<HttpVerb>(['GET', 'HEAD'])
+
+export function isReadOnlyMethod(method: HttpVerb): boolean {
+    return READ_ONLY_METHODS.has(method)
+}

package/src/lib/shared/isStreamingResponse.ts

@@ -0,0 +1,11 @@
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+
+/*
+Whether a Response carries a streaming body (SSE / JSONL / NDJSON) by its
+Content-Type, so callers drain it frame-by-frame instead of buffering.
+Shared by the CLI print path and the MCP tool dispatcher.
+*/
+export function isStreamingResponse(response: Response): boolean {
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    return STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))
+}

package/src/lib/shared/jsonlErrorFrame.ts

@@ -0,0 +1,24 @@
+/*
+The in-band error sentinel for a JSONL/NDJSON stream: when a handler's
+generator throws, `jsonl()` emits a final `{"$error":"<message>"}` line,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel field has one definition and can't drift
+between the two ends of the wire.
+*/
+export const jsonlErrorFrame = {
+    // Error line for a thrown message, including the trailing newline.
+    encode(message: string): string {
+        return `${JSON.stringify({ $error: message })}\n`
+    },
+    // The message carried by a parsed line, or undefined when it isn't the error sentinel.
+    decode(parsed: unknown): string | undefined {
+        if (
+            parsed &&
+            typeof parsed === 'object' &&
+            typeof (parsed as { $error?: unknown }).$error === 'string'
+        ) {
+            return (parsed as { $error: string }).$error
+        }
+        return undefined
+    },
+}

package/src/lib/shared/keyForRemoteCall.ts

@@ -1,5 +1,6 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
 import { canonicalJson } from './canonicalJson.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
 
 /*
 Derives a cache key from a verb-defined remote function and its args. The
@@ -14,7 +15,7 @@ URLSearchParams).
 */
 export function keyForRemoteCall(method: HttpVerb, url: string, args: unknown): string {
     const prefix = `${method} ${url}`
-    if (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
+    if (!carriesBodyArgs(method)) {
         if (args && typeof args === 'object' && !Array.isArray(args)) {
             const record = args as Record<string, unknown>
             const keys = Object.keys(record).sort()

package/src/lib/shared/resolveClientFlags.ts

@@ -2,17 +2,19 @@ import type { ClientFlags } from './types/ClientFlags.ts'
 
 /*
 Fills in the missing keys of a user-supplied `clients` option. Browser
-defaults to true (the historical surface); mcp/cli default to true only
-when a schema is attached, since exposing an unvalidated handler as a
-tool / shell command is a foot-gun.
+always defaults to true (the historical surface). The mcp/cli auto-on
+defaults are decided by the caller and passed in, since the safe default
+differs per declaration: a read-only verb may auto-expose to MCP while a
+mutating one must not, and sockets gate differently again. Explicit
+values in `flags` always win over the computed defaults.
 */
 export function resolveClientFlags(
     flags: Partial<ClientFlags> | undefined,
-    hasSchema: boolean,
+    defaults: { mcp: boolean; cli: boolean },
 ): ClientFlags {
     return {
         browser: flags?.browser ?? true,
-        mcp: flags?.mcp ?? hasSchema,
-        cli: flags?.cli ?? hasSchema,
+        mcp: flags?.mcp ?? defaults.mcp,
+        cli: flags?.cli ?? defaults.cli,
     }
 }

package/src/lib/shared/responseErrorText.ts

@@ -0,0 +1,9 @@
+/*
+Human-readable message for a non-2xx Response: `status statusText: body`.
+Shared by the CLI error path and the MCP tool result so the two frame a
+failed request identically. Consumes the body, so call only on a response
+you're done with.
+*/
+export async function responseErrorText(response: Response): Promise<string> {
+    return `${response.status} ${response.statusText}: ${await response.text()}`
+}

package/src/lib/shared/sseErrorFrame.ts

@@ -0,0 +1,29 @@
+/*
+The in-band error sentinel for an SSE stream: when a handler's generator
+throws, `sse()` emits an `event: error` frame whose data is `{ message }`,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel (event name + payload shape) has one
+definition and can't drift between the two ends of the wire.
+*/
+export const sseErrorFrame = {
+    // Full `event: error` frame for a thrown message, including the SSE delimiters.
+    encode(message: string): string {
+        return `event: error\ndata: ${JSON.stringify({ message })}\n\n`
+    },
+    /*
+    The message carried by an error frame, or undefined when `event` isn't
+    the error sentinel. Falls back to the raw data when it isn't the JSON
+    the encoder produces.
+    */
+    decode(event: string, data: string): string | undefined {
+        if (event !== 'error') {
+            return undefined
+        }
+        try {
+            const decoded = JSON.parse(data) as { message?: string }
+            return decoded?.message ?? 'sse stream error'
+        } catch {
+            return data || 'sse stream error'
+        }
+    },
+}

package/src/lib/shared/streamResponse.ts

@@ -0,0 +1,168 @@
+import { HttpError } from '../server/HttpError.ts'
+import { decodeResponse } from './decodeResponse.ts'
+import { jsonlErrorFrame } from './jsonlErrorFrame.ts'
+import { sseErrorFrame } from './sseErrorFrame.ts'
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+
+/*
+Turns a Response into an AsyncIterable of frames, regardless of the
+handler's chosen body format. Shared by `fn.stream(args)` (via
+subscribableFromResponse), the CLI's streaming print path, and the MCP
+tool dispatcher's stream drain — so every surface consumes sse/jsonl
+identically. Three shapes are handled:
+
+- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
+  each event. The `event: error\ndata: {message}` frame the `sse()`
+  helper emits on generator throws is mapped back to a thrown Error so
+  consumers see the failure mid-iteration.
+- application/jsonl + application/x-ndjson: emits one JSON value per
+  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
+  emits on generator throws is likewise re-thrown.
+- everything else: one-shot — yields the Content-Type-decoded body
+  once, then completes. Lets callers iterate uniformly on every rpc
+  handler, not just the streaming ones.
+
+Non-2xx responses surface as a thrown HttpError on the first pull,
+mirroring the plain `fn(args)` decode path.
+*/
+export function streamResponse<T>(response: Response): AsyncIterable<T> {
+    if (!response.ok) {
+        return errorIterable<T>(new HttpError(response))
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.startsWith('text/event-stream')) {
+        return parseSse<T>(response)
+    }
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        return parseJsonLines<T>(response)
+    }
+    return oneShot<T>(response)
+}
+
+/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
+async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
+    throw error
+}
+
+/*
+One-shot iterator over a non-streaming Response: decodes the body once
+via the same Content-Type sniffing the plain call uses, yields it, then
+completes. Makes streaming symmetrical across streaming and
+non-streaming handlers — callers can pick the iteration shape without
+worrying about which body the handler returned.
+*/
+async function* oneShot<T>(response: Response): AsyncGenerator<T> {
+    yield (await decodeResponse(response)) as T
+}
+
+/*
+Reads a streaming text Response and yields raw frame strings split on
+`delimiter` (`\n\n` for SSE events, `\n` for JSON lines). Owns the whole
+buffering lifecycle: incremental decode, amortised-O(n) compaction, a
+final flush of the trailing partial frame, and reader cancellation when
+the consumer stops iterating (the generator's `finally` runs on
+`return()`). The SSE and jsonl parsers layer their per-frame parsing on
+top of this single machine so the two can't drift.
+*/
+async function* frameReader(response: Response, delimiter: string): AsyncGenerator<string> {
+    const body = response.body
+    if (!body) {
+        return
+    }
+    const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+    let buffer = ''
+    let bufferStart = 0
+    try {
+        while (true) {
+            const { value, done } = await reader.read()
+            if (done) {
+                if (bufferStart < buffer.length) {
+                    yield buffer.slice(bufferStart)
+                }
+                return
+            }
+            /*
+            Compact only when the unread region is small relative to the
+            consumed prefix — keeps amortised work O(n) instead of
+            quadratic slicing per frame boundary.
+            */
+            if (bufferStart > buffer.length / 2) {
+                buffer = buffer.slice(bufferStart) + value
+                bufferStart = 0
+            } else {
+                buffer += value
+            }
+            let boundary = buffer.indexOf(delimiter, bufferStart)
+            while (boundary !== -1) {
+                yield buffer.slice(bufferStart, boundary)
+                bufferStart = boundary + delimiter.length
+                boundary = buffer.indexOf(delimiter, bufferStart)
+            }
+        }
+    } finally {
+        await reader.cancel().catch(() => undefined)
+    }
+}
+
+/*
+SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
+frame. The error sentinel (`sseErrorFrame`) the `sse()` helper emits on a
+generator throw is surfaced as a thrown Error so consumer loops can react
+to mid-stream failure rather than silently stopping.
+*/
+async function* parseSse<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n\n')) {
+        const frame = parseFrame(raw)
+        if (!frame) {
+            continue
+        }
+        const errorMessage = sseErrorFrame.decode(frame.event, frame.data)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield JSON.parse(frame.data) as T
+    }
+}
+
+function parseFrame(raw: string): { event: string; data: string } | undefined {
+    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
+    if (lines.length === 0) {
+        return undefined
+    }
+    let event = 'message'
+    const dataLines: string[] = []
+    for (const line of lines) {
+        const colon = line.indexOf(':')
+        const field = colon === -1 ? line : line.slice(0, colon)
+        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+        if (field === 'event') {
+            event = value
+        } else if (field === 'data') {
+            dataLines.push(value)
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined
+    }
+    return { event, data: dataLines.join('\n') }
+}
+
+/*
+JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
+value. The error sentinel (`jsonlErrorFrame`) the `jsonl()` helper emits as
+a trailing line on a generator throw is surfaced here as a thrown Error so
+consumer loops can react to mid-stream failure.
+*/
+async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n')) {
+        if (raw.length === 0) {
+            continue
+        }
+        const parsed = JSON.parse(raw)
+        const errorMessage = jsonlErrorFrame.decode(parsed)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield parsed as T
+    }
+}