@sumeru/server 0.1.0

package/dist/sse/buffer.js

@@ -0,0 +1,119 @@
+/**
+ * Per-send in-memory ring buffer for SSE resume support.
+ *
+ * Each `POST /gateways/:name/sessions/:id/messages` call creates a fresh
+ * buffer keyed by `(gateway, sessionId, sendNonce)`. Events are appended in
+ * id order; the most-recent N events are retained (N = `sseBufferSize`,
+ * default 1024). After `event: done` the buffer is held for `retentionMs`
+ * (default 30_000) to allow late clients to resume.
+ *
+ * Resume is a pure replay — `adapter.send` is NOT called twice. The buffer
+ * is the canonical record of what the original send produced.
+ */
+let nonceCounter = 0;
+function nextNonce() {
+    nonceCounter += 1;
+    return `n${Date.now().toString(36)}_${nonceCounter}`;
+}
+export function createSseBufferStore(options) {
+    // One buffer per (gateway, sessionId, nonce). We retain the most recent
+    // completed buffer per session so an empty-body Last-Event-ID resume can
+    // find it for a short window.
+    const all = new Map();
+    const latestBySession = new Map();
+    // Ghost set: tracks recently-expired session keys so resume can
+    // distinguish "expired" (410) from "never existed" (404). Entries are
+    // pruned when older than retentionMs past their expiry time.
+    const recentlyExpired = new Map();
+    function key(buf) {
+        return `${buf.gateway}\u0000${buf.sessionId}\u0000${buf.nonce}`;
+    }
+    function sessionKey(gateway, sessionId) {
+        return `${gateway}\u0000${sessionId}`;
+    }
+    function create(gateway, sessionId) {
+        const buf = {
+            gateway,
+            sessionId,
+            nonce: nextNonce(),
+            events: [],
+            maxId: 0,
+            doneAt: null,
+            maxSize: options.maxSize,
+            finished: false,
+        };
+        all.set(key(buf), buf);
+        latestBySession.set(sessionKey(gateway, sessionId), key(buf));
+        return buf;
+    }
+    function getLatestForSession(gateway, sessionId) {
+        const k = latestBySession.get(sessionKey(gateway, sessionId));
+        if (k === undefined)
+            return null;
+        return all.get(k) ?? null;
+    }
+    function finish(buf) {
+        buf.finished = true;
+        buf.doneAt = Date.now();
+    }
+    function purgeExpired(now) {
+        // First, prune ghost entries older than retentionMs past their expiry.
+        for (const [skey, expiredAt] of recentlyExpired) {
+            if (now - expiredAt > options.retentionMs) {
+                recentlyExpired.delete(skey);
+            }
+        }
+        // Then, move expired live buffers to the ghost set before deleting.
+        for (const [k, buf] of all) {
+            if (buf.doneAt !== null && now - buf.doneAt > options.retentionMs) {
+                const skey = sessionKey(buf.gateway, buf.sessionId);
+                recentlyExpired.set(skey, now);
+                all.delete(k);
+                if (latestBySession.get(skey) === k) {
+                    latestBySession.delete(skey);
+                }
+            }
+        }
+    }
+    function wasRecentlyExpired(gateway, sessionId) {
+        return recentlyExpired.has(sessionKey(gateway, sessionId));
+    }
+    return {
+        create,
+        getLatestForSession,
+        finish,
+        purgeExpired,
+        wasRecentlyExpired,
+    };
+}
+/** Append an event to a buffer, maintaining `maxSize` ring semantics. */
+export function appendEvent(buf, event, data) {
+    const id = buf.maxId + 1;
+    buf.maxId = id;
+    const evt = { id, event, data };
+    buf.events.push(evt);
+    if (buf.events.length > buf.maxSize) {
+        buf.events.shift();
+    }
+    return evt;
+}
+/** Wire-format an event: `id: ...\nevent: ...\ndata: ...\n\n`. */
+export function formatEvent(evt) {
+    return `id: ${evt.id}\nevent: ${evt.event}\ndata: ${evt.data}\n\n`;
+}
+/** Range-replay events whose id is strictly greater than `since`. */
+export function eventsAfter(buf, since) {
+    if (since < 0)
+        return buf.events.slice();
+    return buf.events.filter((e) => e.id > since);
+}
+/**
+ * Lowest still-buffered event id, or 0 when empty. Useful when computing
+ * whether a Last-Event-ID predates the ring's current window.
+ */
+export function lowestId(buf) {
+    if (buf.events.length === 0)
+        return 0;
+    return buf.events[0]?.id ?? 0;
+}
+//# sourceMappingURL=buffer.js.map

package/dist/sse/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/sse/buffer.ts"],"names":[],"mappings":"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"}

package/dist/sse/index.d.ts

@@ -0,0 +1,3 @@
+export { appendEvent, createSseBufferStore, eventsAfter, formatEvent, lowestId, type SseBuffer, type SseBufferOptions, type SseBufferStore, type SseEvent, } from "./buffer.js";
+export { handleMessageEndpoint, type MessageEndpointDeps, makeMessageBufferStore, } from "./messages.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sse/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sse/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,QAAQ,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,sBAAsB,GACtB,MAAM,eAAe,CAAC"}

package/dist/sse/index.js

@@ -0,0 +1,3 @@
+export { appendEvent, createSseBufferStore, eventsAfter, formatEvent, lowestId, } from "./buffer.js";
+export { handleMessageEndpoint, makeMessageBufferStore, } from "./messages.js";
+//# sourceMappingURL=index.js.map

package/dist/sse/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sse/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,QAAQ,GAKR,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,qBAAqB,EAErB,sBAAsB,GACtB,MAAM,eAAe,CAAC"}

package/dist/sse/messages.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SSE message endpoint — `POST /gateways/:name/sessions/:id/messages`.
+ *
+ * Streams turn / heartbeat / done / error events generated by the gateway's
+ * adapter. Supports `Last-Event-ID` header for resume from in-memory buffer.
+ *
+ * Phase 4: each user/assistant turn is also written to ocas before its SSE
+ * event is emitted; the resulting hash is stamped onto the SSE payload's
+ * `value.hash` and appended to `Session.turnHashes` so the history endpoint
+ * can replay it.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Adapter } from "@sumeru/core";
+import type { SessionStore } from "../session/index.js";
+import type { ServerConfig } from "../types.js";
+import { type SseBufferStore } from "./buffer.js";
+export type MessageEndpointDeps = {
+    sessions: SessionStore;
+    adapters: Record<string, Adapter>;
+    config: ServerConfig;
+    bufferStore: SseBufferStore;
+};
+/** Build an isolated buffer store per server instance. */
+export declare function makeMessageBufferStore(config: ServerConfig): SseBufferStore;
+/**
+ * Handle the SSE message endpoint. Performs body validation, status flips,
+ * adapter invocation, and event emission.
+ */
+export declare function handleMessageEndpoint(req: IncomingMessage, res: ServerResponse, gatewayName: string, sessionId: string, deps: MessageEndpointDeps): Promise<void>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/sse/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/sse/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,cAAc,CAAC;AAGlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAON,KAAK,cAAc,EACnB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,mBAAmB,GAAG;IACjC,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,cAAc,CAAC;CAC5B,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAK3E;AAmCD;;;GAGG;AACH,wBAAsB,qBAAqB,CAC1C,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,GACvB,OAAO,CAAC,IAAI,CAAC,CAsZf"}

package/dist/sse/messages.js

@@ -0,0 +1,489 @@
+/**
+ * SSE message endpoint — `POST /gateways/:name/sessions/:id/messages`.
+ *
+ * Streams turn / heartbeat / done / error events generated by the gateway's
+ * adapter. Supports `Last-Event-ID` header for resume from in-memory buffer.
+ *
+ * Phase 4: each user/assistant turn is also written to ocas before its SSE
+ * event is emitted; the resulting hash is stamped onto the SSE payload's
+ * `value.hash` and appended to `Session.turnHashes` so the history endpoint
+ * can replay it.
+ */
+import { SchemaValidationError } from "@ocas/core";
+import { errorEnvelope } from "../envelope.js";
+import { recordPayload } from "../ocas/index.js";
+import { appendEvent, createSseBufferStore, eventsAfter, formatEvent, lowestId, } from "./buffer.js";
+/** Build an isolated buffer store per server instance. */
+export function makeMessageBufferStore(config) {
+    return createSseBufferStore({
+        maxSize: config.sseBufferSize,
+        retentionMs: config.sseRetentionMs,
+    });
+}
+function parseLastEventId(headerValue) {
+    if (headerValue === undefined)
+        return { ok: true, value: null };
+    const trimmed = headerValue.trim();
+    if (trimmed === "") {
+        return {
+            ok: false,
+            message: "Last-Event-ID header is present but empty",
+        };
+    }
+    if (!/^[0-9]+$/.test(trimmed)) {
+        return {
+            ok: false,
+            message: `Last-Event-ID must be a non-negative integer (got '${headerValue}')`,
+        };
+    }
+    const n = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        return {
+            ok: false,
+            message: `Last-Event-ID must be a non-negative integer (got '${headerValue}')`,
+        };
+    }
+    return { ok: true, value: n };
+}
+/**
+ * Handle the SSE message endpoint. Performs body validation, status flips,
+ * adapter invocation, and event emission.
+ */
+export async function handleMessageEndpoint(req, res, gatewayName, sessionId, deps) {
+    const { sessions, adapters, config, bufferStore } = deps;
+    bufferStore.purgeExpired(Date.now());
+    const session = sessions.get(gatewayName, sessionId);
+    if (session === null) {
+        writeJson(res, 404, errorEnvelope("session_not_found", `Session ${sessionId} not found on gateway ${gatewayName}`));
+        return;
+    }
+    if (session.status === "closed") {
+        writeJson(res, 404, errorEnvelope("session_not_found", `Session ${sessionId} not found on gateway ${gatewayName}`));
+        return;
+    }
+    const lastEventIdRaw = readHeader(req, "last-event-id");
+    const lastEventId = parseLastEventId(lastEventIdRaw);
+    if (!lastEventId.ok) {
+        writeJson(res, 400, errorEnvelope("invalid_last_event_id", lastEventId.message));
+        return;
+    }
+    const body = await readJsonBody(req);
+    if (!body.ok) {
+        writeJson(res, 400, errorEnvelope(body.error, body.message));
+        return;
+    }
+    const isResumeOnly = lastEventId.value !== null && body.value.contentMissing === true;
+    const isResumeWithBody = lastEventId.value !== null && body.value.contentMissing !== true;
+    const lastEventIdValue = lastEventId.value;
+    // Empty-body resume: pure replay
+    if (isResumeOnly && lastEventIdValue !== null) {
+        await handleResumeOnly(res, gatewayName, sessionId, lastEventIdValue, bufferStore, config);
+        return;
+    }
+    // Validate content: required for new send AND resume-with-body
+    if (body.value.contentMissing === true) {
+        writeJson(res, 400, errorEnvelope("invalid_request", "Missing required field 'content'"));
+        return;
+    }
+    if (body.value.content === "") {
+        writeJson(res, 400, errorEnvelope("invalid_request", "Field 'content' must be a non-empty string"));
+        return;
+    }
+    // Adapter is keyed by adapter NAME (from gateway config), not gateway name.
+    const gatewayCfg = config.gateways[session.gateway];
+    const adapterByName = gatewayCfg !== undefined ? adapters[gatewayCfg.adapter] : undefined;
+    if (adapterByName === undefined) {
+        writeJson(res, 503, errorEnvelope("adapter_unavailable", `Adapter '${gatewayCfg?.adapter ?? "(unknown)"}' is not registered for gateway '${session.gateway}'`));
+        return;
+    }
+    // Resume-with-body: continue an existing buffer if one is live, else 404.
+    if (isResumeWithBody && lastEventIdValue !== null) {
+        const buf = bufferStore.getLatestForSession(gatewayName, sessionId);
+        if (buf === null) {
+            if (bufferStore.wasRecentlyExpired(gatewayName, sessionId)) {
+                writeJson(res, 410, errorEnvelope("stream_expired", `SSE stream for session ${sessionId} has expired (retained ${Math.round(config.sseRetentionMs / 1000)}s after completion)`));
+                return;
+            }
+            writeJson(res, 404, errorEnvelope("no_event_buffer", `No buffered SSE stream to resume on session ${sessionId}`));
+            return;
+        }
+        await streamFromBufferThenLive(res, buf, lastEventIdValue, config);
+        return;
+    }
+    // Concurrency check (idle → active). Resume cases handled above.
+    const transition = sessions.tryActivate(gatewayName, sessionId);
+    if (!transition.ok) {
+        const reason = transition.reason;
+        if (reason === "busy") {
+            writeJson(res, 409, errorEnvelope("session_busy", `Session ${sessionId} is currently active`));
+            return;
+        }
+        if (reason === "closed") {
+            writeJson(res, 404, errorEnvelope("session_not_found", `Session ${sessionId} not found on gateway ${gatewayName}`));
+            return;
+        }
+        writeJson(res, 404, errorEnvelope("session_not_found", `Session ${sessionId} not found on gateway ${gatewayName}`));
+        return;
+    }
+    const nativeRef = sessions.getNativeRef(gatewayName, sessionId);
+    if (nativeRef === null) {
+        sessions.markIdle(gatewayName, sessionId);
+        writeJson(res, 503, errorEnvelope("adapter_unavailable", `Session ${sessionId} has no native ref recorded — adapter likely failed at create time`));
+        return;
+    }
+    // Write the user turn to ocas BEFORE invoking adapter.send. The session has
+    // been activated; if the write fails we restore idle and return 500.
+    const userTurnIndex = session.turnHashes.length;
+    const userTurn = {
+        index: userTurnIndex,
+        role: "user",
+        content: body.value.content,
+        timestamp: new Date().toISOString(),
+        toolCalls: null,
+        tokens: null,
+        hash: null,
+    };
+    const userPayload = turnPayload(userTurn);
+    let userHash;
+    try {
+        userHash = recordPayload(config.ocas.store, config.ocas.turnSchemaHash, userPayload);
+    }
+    catch (err) {
+        sessions.markIdle(gatewayName, sessionId);
+        const cause = err instanceof Error ? err.message : String(err);
+        const code = err instanceof SchemaValidationError
+            ? "ocas_validation_failed"
+            : "ocas_write_failed";
+        writeJson(res, 500, errorEnvelope(code, `Failed to record user turn: ${truncate(cause, 500)}`));
+        return;
+    }
+    // Phase 5: index the user turn for FTS5 search BEFORE appending the hash
+    // or starting the SSE stream. If indexing fails the ocas write stays —
+    // the index can be rebuilt — but the request fails fast.
+    try {
+        config.ocas.searchIndex.indexTurn({
+            turnHash: userHash,
+            sessionId,
+            gateway: gatewayName,
+            turnIndex: userTurn.index,
+            role: "user",
+            content: userTurn.content,
+            createdAt: userTurn.timestamp,
+        });
+    }
+    catch (err) {
+        sessions.markIdle(gatewayName, sessionId);
+        const cause = err instanceof Error ? err.message : String(err);
+        writeJson(res, 500, errorEnvelope("search_index_failed", `Failed to update search index: ${truncate(cause, 500)}`));
+        return;
+    }
+    // Phase 6 (Refs #399): persist the turn-list pointer. A failure here must
+    // not silently diverge memory from disk — fail fast with a clean 500 before
+    // the SSE stream starts (headers are written just below).
+    try {
+        sessions.appendTurnHash(gatewayName, sessionId, userHash);
+    }
+    catch (err) {
+        sessions.markIdle(gatewayName, sessionId);
+        const cause = err instanceof Error ? err.message : String(err);
+        writeJson(res, 500, errorEnvelope("turn_persist_failed", `Failed to persist turn list: ${truncate(cause, 500)}`));
+        return;
+    }
+    const buf = bufferStore.create(gatewayName, sessionId);
+    writeSseHeaders(res);
+    const startedAt = Date.now();
+    const heartbeatTimer = startHeartbeats(res, buf, startedAt, config);
+    let turnCount = 0;
+    try {
+        for await (const event of adapterByName.send(nativeRef, body.value.content)) {
+            if (event.type === "turn") {
+                const turn = event.turn;
+                const payload = turnPayload(turn);
+                let hash;
+                try {
+                    hash = recordPayload(config.ocas.store, config.ocas.turnSchemaHash, payload);
+                }
+                catch (err) {
+                    const cause = err instanceof Error ? err.message : String(err);
+                    const reason = err instanceof SchemaValidationError
+                        ? "adapter_returned_invalid_turn"
+                        : "ocas_write_failed";
+                    const errEvt = appendEvent(buf, "error", JSON.stringify({
+                        type: "@sumeru/error",
+                        value: { error: reason, message: truncate(cause, 500) },
+                    }));
+                    res.write(formatEvent(errEvt));
+                    break;
+                }
+                try {
+                    config.ocas.searchIndex.indexTurn({
+                        turnHash: hash,
+                        sessionId,
+                        gateway: gatewayName,
+                        turnIndex: turn.index,
+                        role: turn.role,
+                        content: turn.content,
+                        createdAt: turn.timestamp,
+                    });
+                }
+                catch (err) {
+                    const cause = err instanceof Error ? err.message : String(err);
+                    const errEvt = appendEvent(buf, "error", JSON.stringify({
+                        type: "@sumeru/error",
+                        value: {
+                            error: "search_index_failed",
+                            message: `Failed to update search index: ${truncate(cause, 500)}`,
+                        },
+                    }));
+                    res.write(formatEvent(errEvt));
+                    break;
+                }
+                try {
+                    sessions.appendTurnHash(gatewayName, sessionId, hash);
+                }
+                catch (err) {
+                    const cause = err instanceof Error ? err.message : String(err);
+                    const errEvt = appendEvent(buf, "error", JSON.stringify({
+                        type: "@sumeru/error",
+                        value: {
+                            error: "turn_persist_failed",
+                            message: `Failed to persist turn list: ${truncate(cause, 500)}`,
+                        },
+                    }));
+                    res.write(formatEvent(errEvt));
+                    break;
+                }
+                const wireTurn = { ...turn, hash };
+                const evt = appendEvent(buf, "turn", JSON.stringify({ type: "@sumeru/turn", value: wireTurn }));
+                res.write(formatEvent(evt));
+                turnCount += 1;
+            }
+            else if (event.type === "done") {
+                const summary = {
+                    turnCount,
+                    tokens: event.tokens === null
+                        ? null
+                        : { in: event.tokens.input, out: event.tokens.output },
+                    durationMs: event.durationMs,
+                };
+                const doneEvt = appendEvent(buf, "done", JSON.stringify({ type: "@sumeru/summary", value: summary }));
+                res.write(formatEvent(doneEvt));
+            }
+            else if (event.type === "error") {
+                const errEvt = appendEvent(buf, "error", JSON.stringify({
+                    type: "@sumeru/error",
+                    value: {
+                        error: "adapter_error",
+                        message: truncate(event.error.message, 500),
+                    },
+                }));
+                res.write(formatEvent(errEvt));
+            }
+        }
+    }
+    catch (err) {
+        const adapterError = err instanceof Error ? err : new Error(String(err));
+        const errEvt = appendEvent(buf, "error", JSON.stringify({
+            type: "@sumeru/error",
+            value: {
+                error: "adapter_error",
+                message: truncate(adapterError.message, 500),
+            },
+        }));
+        res.write(formatEvent(errEvt));
+    }
+    finally {
+        clearInterval(heartbeatTimer);
+        sessions.markIdle(gatewayName, sessionId);
+    }
+    bufferStore.finish(buf);
+    res.end();
+}
+/**
+ * Strip server-only / nullable fields from a Turn before recording so the
+ * payload conforms to `@sumeru/turn`. The schema rejects extra fields
+ * (`additionalProperties: false`); also drops `tokens` when null/absent and
+ * `hash` (always server-injected, never persisted INSIDE the payload).
+ */
+function turnPayload(turn) {
+    const out = {
+        index: turn.index,
+        role: turn.role,
+        content: turn.content,
+        timestamp: turn.timestamp,
+        toolCalls: turn.toolCalls,
+    };
+    if (turn.tokens !== undefined && turn.tokens !== null) {
+        out.tokens = { input: turn.tokens.input, output: turn.tokens.output };
+    }
+    return out;
+}
+async function handleResumeOnly(res, gatewayName, sessionId, since, bufferStore, config) {
+    const buf = bufferStore.getLatestForSession(gatewayName, sessionId);
+    if (buf === null) {
+        if (bufferStore.wasRecentlyExpired(gatewayName, sessionId)) {
+            writeJson(res, 410, errorEnvelope("stream_expired", `SSE stream for session ${sessionId} has expired (retained ${Math.round(config.sseRetentionMs / 1000)}s after completion)`));
+            return;
+        }
+        writeJson(res, 404, errorEnvelope("no_event_buffer", `No buffered SSE stream to resume on session ${sessionId}`));
+        return;
+    }
+    if (since > buf.maxId) {
+        writeJson(res, 400, errorEnvelope("invalid_last_event_id", `Last-Event-ID ${since} is greater than the highest known event id ${buf.maxId}`));
+        return;
+    }
+    if (buf.doneAt !== null && Date.now() - buf.doneAt > buf.maxSize * 0) {
+        // retention check is handled by purgeExpired; if buf still resolves we can replay.
+    }
+    const lowest = lowestId(buf);
+    if (lowest > 0 && since < lowest - 1) {
+        writeJson(res, 410, errorEnvelope("events_evicted", `Last-Event-ID ${since} is older than the lowest still-buffered event ${lowest}`));
+        return;
+    }
+    writeSseHeaders(res);
+    const remaining = eventsAfter(buf, since);
+    for (const evt of remaining) {
+        res.write(formatEvent(evt));
+    }
+    res.end();
+}
+async function streamFromBufferThenLive(res, buf, since, _config) {
+    if (since > buf.maxId) {
+        writeJson(res, 400, errorEnvelope("invalid_last_event_id", `Last-Event-ID ${since} is greater than the highest known event id ${buf.maxId}`));
+        return;
+    }
+    const lowest = lowestId(buf);
+    if (lowest > 0 && since < lowest - 1) {
+        writeJson(res, 410, errorEnvelope("events_evicted", `Last-Event-ID ${since} is older than the lowest still-buffered event ${lowest}`));
+        return;
+    }
+    writeSseHeaders(res);
+    let cursor = since;
+    const flushPending = () => {
+        const events = eventsAfter(buf, cursor);
+        for (const evt of events) {
+            res.write(formatEvent(evt));
+            cursor = Math.max(cursor, evt.id);
+        }
+        return buf.finished;
+    };
+    if (flushPending()) {
+        res.end();
+        return;
+    }
+    // Poll the buffer until finished. The original send writes events to this
+    // same buffer; resume just mirrors them out on the new connection.
+    await new Promise((resolve) => {
+        const poll = setInterval(() => {
+            const finished = flushPending();
+            if (finished) {
+                clearInterval(poll);
+                res.end();
+                resolve();
+            }
+        }, 25);
+        res.once("close", () => {
+            clearInterval(poll);
+            resolve();
+        });
+    });
+}
+function writeSseHeaders(res) {
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    // Disable Nagle's algorithm so each res.write() flushes immediately.
+    // Without this, SSE events (heartbeats, turns, done) are buffered by
+    // the TCP stack and never reach the client — the broker's consumeSse
+    // blocks on reader.read() forever. Fixes #30.
+    res.socket?.setNoDelay(true);
+    res.flushHeaders?.();
+}
+function startHeartbeats(res, buf, startedAt, config) {
+    const timer = setInterval(() => {
+        const elapsed = Date.now() - startedAt;
+        const evt = appendEvent(buf, "heartbeat", JSON.stringify({
+            type: "@sumeru/heartbeat",
+            value: { elapsed },
+        }));
+        res.write(formatEvent(evt));
+    }, Math.max(50, config.sseHeartbeatMs));
+    timer.unref();
+    return timer;
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+function readHeader(req, name) {
+    const value = req.headers[name];
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    const MAX = 1024 * 1024;
+    for await (const chunk of req) {
+        const buf = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > MAX) {
+            return {
+                ok: false,
+                error: "invalid_request",
+                message: "Request body too large",
+            };
+        }
+        chunks.push(buf);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    if (raw.length === 0) {
+        return { ok: true, value: { content: "", contentMissing: true } };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: "invalid_json",
+            message: `Request body is not valid JSON: ${detail}`,
+        };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            error: "invalid_request",
+            message: "Request body must be a JSON object",
+        };
+    }
+    const obj = parsed;
+    if (!("content" in obj)) {
+        return { ok: true, value: { content: "", contentMissing: true } };
+    }
+    const content = obj.content;
+    if (typeof content !== "string") {
+        return {
+            ok: false,
+            error: "invalid_request",
+            message: "Field 'content' must be a string",
+        };
+    }
+    return { ok: true, value: { content, contentMissing: false } };
+}
+function writeJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.setHeader("Content-Length", Buffer.byteLength(payload).toString());
+    res.end(payload);
+}
+//# sourceMappingURL=messages.js.map