infinicode 1.0.0 → 2.1.0

package/dist/kernel/federation/moltfed-adapter.js

@@ -0,0 +1,52 @@
+/** InfiniBot `nodes.status` / `node.list` response shape. */
+export function toNodesStatus(statuses) {
+    return {
+        ts: Date.now(),
+        nodes: statuses.map(s => ({
+            nodeId: s.nodeId,
+            displayName: s.displayName,
+            platform: s.platform,
+            deviceFamily: s.deviceFamily,
+            modelIdentifier: s.modelIdentifier,
+            version: s.version,
+            caps: s.capabilities,
+            commands: s.commands,
+            connected: s.connected,
+            connectedAtMs: s.connectedAtMs,
+            paired: true,
+            // extra infinicode fields are ignored by InfiniBot but useful to richer UIs
+            role: s.role,
+            load: s.load,
+        })),
+    };
+}
+/** InfiniBot `hardware.snapshot` payload (shape already matches). */
+export function toHardwareSnapshot(nodeId, hw) {
+    return { nodeId, snapshot: hw };
+}
+/** Map a compact activity/routing frame to an InfiniBot-style `agent` event. */
+export function toAgentEvent(f) {
+    if (f.t !== 'ev' && f.t !== 'rt')
+        return null;
+    const d = (f.d ?? {});
+    return {
+        source: 'infinicode',
+        nodeId: f.n,
+        seq: f.s,
+        ts: f.ts,
+        kind: d.k,
+        missionId: d.m,
+        taskId: d.task,
+        workerId: d.w,
+        data: d.d,
+    };
+}
+/** Build the full set of InfiniBot-bound messages for a periodic push. */
+export function buildMoltfedBatch(statuses, selfId, hw) {
+    const out = [
+        { method: 'nodes.status', params: toNodesStatus(statuses) },
+    ];
+    if (hw)
+        out.push({ method: 'hardware.snapshot', params: toHardwareSnapshot(selfId, hw) });
+    return out;
+}

package/dist/kernel/federation/moltfed-connector.d.ts

@@ -0,0 +1,98 @@
+/**
+ * OpenKernel — MOLTFED / InfiniBot Gateway Connector
+ *
+ * Logs an infinicode node into an InfiniBot gateway over WebSocket and streams
+ * it onto InfiniBot's neural-mesh map + hardware panels — WITHOUT editing
+ * InfiniBot. It speaks InfiniBot's gateway protocol (observed in InfiniBot
+ * src/mcp/server.ts):
+ *
+ *   1. open ws://<host>:18789
+ *   2. optionally receive event `connect.challenge` → nonce
+ *   3. send { type:'req', id, method:'connect', params:{ minProtocol, client,
+ *      auth, role, scopes, device } }
+ *   4. receive `hello-ok` → connected
+ *   5. push request frames: { type:'req', id, method, params }
+ *
+ * Auth is PLUGGABLE (token/password by default; a device-signer can be supplied
+ * for gateways that require signed device identity). Push method names are
+ * CONFIGURABLE so this adapts to a gateway's exact method registry without code
+ * changes. The WebSocket impl is injectable for testing.
+ *
+ * NOTE: verify end-to-end against a live InfiniBot gateway; the frame shapes
+ * here mirror the observed protocol but a given gateway version may differ.
+ */
+import type { Logger } from '../types.js';
+import type { NodeStatus, HardwareSnapshot, StreamFrame } from './types.js';
+/** Minimal browser-style WebSocket surface (Node global WebSocket / ws both fit). */
+export interface WsLike {
+    send(data: string): void;
+    close(): void;
+    onopen: ((ev?: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev?: unknown) => void) | null;
+    onerror: ((ev?: unknown) => void) | null;
+}
+export type WsFactory = (url: string) => WsLike;
+export interface DeviceAuth {
+    id: string;
+    publicKey: string;
+    /** Sign the connect payload (nonce-bound). Return a signature string. */
+    sign: (payload: unknown, nonce: string | null, signedAt: number) => string;
+}
+export interface MoltfedConnectorOptions {
+    gatewayUrl: string;
+    token?: string;
+    password?: string;
+    client?: {
+        id: string;
+        version: string;
+        platform: string;
+        mode: string;
+    };
+    role?: string;
+    scopes?: string[];
+    device?: DeviceAuth;
+    minProtocol?: number;
+    maxProtocol?: number;
+    pushIntervalMs?: number;
+    logger: Logger;
+    /** Data sources — usually bound to a Federation instance. */
+    getNodeStatuses: () => NodeStatus[];
+    getHardware: () => HardwareSnapshot | undefined;
+    subscribeFrames: (cb: (peerId: string, f: StreamFrame) => void) => () => void;
+    /** Gateway method names (defaults chosen to match observed InfiniBot usage). */
+    methodNodes?: string;
+    methodHardware?: string;
+    methodAgent?: string;
+    /** Injectable WS constructor for tests; defaults to global WebSocket. */
+    wsFactory?: WsFactory;
+}
+export declare class MoltfedConnector {
+    private opts;
+    private ws;
+    private connected;
+    private nonce;
+    private connectId;
+    private connectSent;
+    private pushTimer?;
+    private connectTimer?;
+    private unsubFrames?;
+    private stopped;
+    private reconnectAttempts;
+    constructor(opts: MoltfedConnectorOptions);
+    get isConnected(): boolean;
+    start(): void;
+    private open;
+    private onMessage;
+    private buildConnectFrame;
+    private sendConnect;
+    private onConnected;
+    private pushSnapshot;
+    /** Send a request frame (fire-and-forget; gateway acks via res). */
+    request(method: string, params: unknown): void;
+    private scheduleReconnect;
+    private stopPush;
+    stop(): void;
+}

package/dist/kernel/federation/moltfed-connector.js

@@ -0,0 +1,193 @@
+import { toNodesStatus, toHardwareSnapshot, toAgentEvent } from './moltfed-adapter.js';
+let reqSeq = 0;
+function reqId() {
+    reqSeq = (reqSeq + 1) % Number.MAX_SAFE_INTEGER;
+    return `oc_${Date.now().toString(36)}_${reqSeq}`;
+}
+export class MoltfedConnector {
+    opts;
+    ws = null;
+    connected = false;
+    nonce = null;
+    connectId = null;
+    connectSent = false;
+    pushTimer;
+    connectTimer;
+    unsubFrames;
+    stopped = false;
+    reconnectAttempts = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    start() {
+        this.stopped = false;
+        this.open();
+    }
+    open() {
+        if (this.stopped)
+            return;
+        const factory = this.opts.wsFactory
+            ?? ((url) => new globalThis.WebSocket(url));
+        let socket;
+        try {
+            socket = factory(this.opts.gatewayUrl);
+        }
+        catch (err) {
+            this.opts.logger.warn(`[moltfed] cannot open ${this.opts.gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = socket;
+        this.connected = false;
+        this.connectSent = false;
+        this.connectId = null;
+        socket.onopen = () => {
+            this.opts.logger.info(`[moltfed] socket open → ${this.opts.gatewayUrl}`);
+            // If no challenge arrives, send connect after a short delay (mirrors InfiniBot).
+            this.connectTimer = setTimeout(() => this.sendConnect(), 750);
+        };
+        socket.onmessage = (ev) => this.onMessage(String(ev.data));
+        socket.onerror = () => { };
+        socket.onclose = () => {
+            if (this.ws !== socket)
+                return;
+            this.connected = false;
+            this.ws = null;
+            this.opts.logger.warn('[moltfed] gateway connection closed');
+            this.stopPush();
+            this.scheduleReconnect();
+        };
+    }
+    onMessage(text) {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (msg.type === 'event' && msg.event === 'connect.challenge') {
+            const payload = msg.payload;
+            if (payload?.nonce) {
+                this.nonce = payload.nonce;
+                this.sendConnect();
+            }
+            return;
+        }
+        const helloOk = msg.type === 'hello-ok'
+            || (msg.type === 'res' && msg.payload?.type === 'hello-ok')
+            || (msg.type === 'res' && msg.id === this.connectId && msg.ok === true);
+        if (helloOk) {
+            this.onConnected();
+        }
+    }
+    buildConnectFrame(id) {
+        const o = this.opts;
+        const signedAt = Date.now();
+        const client = o.client ?? { id: 'infinicode', version: '2.0.0', platform: 'node', mode: 'backend' };
+        const params = {
+            minProtocol: o.minProtocol ?? 3,
+            maxProtocol: o.maxProtocol ?? 3,
+            client,
+            caps: [],
+            role: o.role ?? 'operator',
+            scopes: o.scopes ?? ['operator.admin'],
+        };
+        if (o.token || o.password) {
+            params.auth = { token: o.token, password: o.password || undefined };
+        }
+        if (o.device) {
+            params.device = {
+                id: o.device.id,
+                publicKey: o.device.publicKey,
+                signature: o.device.sign(params, this.nonce, signedAt),
+                signedAt,
+                nonce: this.nonce ?? undefined,
+            };
+        }
+        return { type: 'req', id, method: 'connect', params };
+    }
+    sendConnect() {
+        if (this.connectSent || !this.ws)
+            return;
+        this.connectSent = true;
+        if (this.connectTimer) {
+            clearTimeout(this.connectTimer);
+            this.connectTimer = undefined;
+        }
+        this.connectId = reqId();
+        const frame = this.buildConnectFrame(this.connectId);
+        try {
+            this.ws.send(JSON.stringify(frame));
+            this.opts.logger.info('[moltfed] connect frame sent');
+        }
+        catch (err) {
+            this.opts.logger.warn(`[moltfed] connect send failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    onConnected() {
+        if (this.connected)
+            return;
+        this.connected = true;
+        this.reconnectAttempts = 0;
+        this.opts.logger.info('[moltfed] handshake ok — node is live on the gateway');
+        this.pushSnapshot(); // immediate first paint
+        this.pushTimer = setInterval(() => this.pushSnapshot(), this.opts.pushIntervalMs ?? 2000);
+        // Stream activity/routing frames as agent events for map animation.
+        this.unsubFrames = this.opts.subscribeFrames((_peer, f) => {
+            const evt = toAgentEvent(f);
+            if (evt)
+                this.request(this.opts.methodAgent ?? 'agent.event', evt);
+        });
+    }
+    pushSnapshot() {
+        if (!this.connected)
+            return;
+        this.request(this.opts.methodNodes ?? 'nodes.status', toNodesStatus(this.opts.getNodeStatuses()));
+        const hw = this.opts.getHardware();
+        if (hw) {
+            const selfId = this.opts.getNodeStatuses().find(s => s.connected)?.nodeId ?? 'infinicode';
+            this.request(this.opts.methodHardware ?? 'hardware.snapshot', toHardwareSnapshot(selfId, hw));
+        }
+    }
+    /** Send a request frame (fire-and-forget; gateway acks via res). */
+    request(method, params) {
+        if (!this.ws)
+            return;
+        try {
+            this.ws.send(JSON.stringify({ type: 'req', id: reqId(), method, params }));
+        }
+        catch {
+            /* dropped — next push will retry state */
+        }
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        this.reconnectAttempts++;
+        const delay = Math.min(30_000, 1000 * 2 ** Math.min(this.reconnectAttempts, 5));
+        setTimeout(() => this.open(), delay);
+    }
+    stopPush() {
+        if (this.pushTimer)
+            clearInterval(this.pushTimer);
+        this.pushTimer = undefined;
+        this.unsubFrames?.();
+        this.unsubFrames = undefined;
+    }
+    stop() {
+        this.stopped = true;
+        this.stopPush();
+        if (this.connectTimer)
+            clearTimeout(this.connectTimer);
+        try {
+            this.ws?.close();
+        }
+        catch { /* ignore */ }
+        this.ws = null;
+        this.connected = false;
+    }
+}

package/dist/kernel/federation/node-identity.d.ts

@@ -0,0 +1,19 @@
+import type { NodeIdentity, NodeManifest, NodeRole } from './types.js';
+export interface IdentityOptions {
+    storageDir?: string;
+    displayName?: string;
+    role?: NodeRole;
+}
+/** Load the persisted identity or create + persist a fresh one. */
+export declare function loadOrCreateIdentity(opts?: IdentityOptions): NodeIdentity;
+export interface ManifestInputs {
+    version: string;
+    capabilities: NodeManifest['capabilities'];
+    workers: string[];
+    commands: string[];
+    providers: string[];
+}
+/** Build the manifest advertised to peers + the mesh map. */
+export declare function buildManifest(identity: NodeIdentity, inputs: ManifestInputs): NodeManifest;
+/** Total memory in bytes — used by telemetry + routing. */
+export declare function totalMemoryBytes(): number;

package/dist/kernel/federation/node-identity.js

@@ -0,0 +1,86 @@
+/**
+ * OpenKernel — Node Identity
+ *
+ * A stable, persisted identity for this device so it keeps the same nodeId
+ * across restarts (the mesh map + peers track it by id). Stored as JSON under
+ * the kernel storage dir. No crypto dependency — the optional keypair is a
+ * lightweight placeholder that app-layer auth can fill in later.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { hostname, platform, arch, cpus, totalmem } from 'node:os';
+import { join } from 'node:path';
+import { nanoid } from 'nanoid';
+function defaultStorageDir() {
+    return join(process.cwd(), '.openkernel');
+}
+/** Best-effort device family label from platform + memory + CPU. */
+function detectDeviceFamily() {
+    const p = platform();
+    const model = cpus()[0]?.model ?? '';
+    if (/raspberry|bcm2|cortex-a/i.test(model) || (arch().startsWith('arm') && p === 'linux')) {
+        return 'Raspberry Pi / ARM';
+    }
+    if (p === 'win32')
+        return 'Windows Workstation';
+    if (p === 'darwin')
+        return 'Mac';
+    if (p === 'linux')
+        return 'Linux';
+    return p;
+}
+/** Load the persisted identity or create + persist a fresh one. */
+export function loadOrCreateIdentity(opts = {}) {
+    const dir = opts.storageDir ?? defaultStorageDir();
+    const file = join(dir, 'node-identity.json');
+    if (existsSync(file)) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            // Allow role/displayName overrides at launch without losing the id.
+            if (opts.role)
+                parsed.role = opts.role;
+            if (opts.displayName)
+                parsed.displayName = opts.displayName;
+            return parsed;
+        }
+        catch {
+            // fall through and recreate
+        }
+    }
+    const identity = {
+        nodeId: `node_${nanoid(10)}`,
+        displayName: opts.displayName ?? hostname(),
+        role: opts.role ?? 'peer',
+        createdAt: Date.now(),
+    };
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(file, JSON.stringify(identity, null, 2));
+    }
+    catch {
+        // non-fatal: run with an ephemeral identity if disk is unavailable
+    }
+    return identity;
+}
+/** Build the manifest advertised to peers + the mesh map. */
+export function buildManifest(identity, inputs) {
+    return {
+        nodeId: identity.nodeId,
+        displayName: identity.displayName,
+        role: identity.role,
+        version: inputs.version,
+        platform: platform(),
+        arch: arch(),
+        deviceFamily: detectDeviceFamily(),
+        modelIdentifier: cpus()[0]?.model,
+        capabilities: inputs.capabilities,
+        workers: inputs.workers,
+        commands: inputs.commands,
+        providers: inputs.providers,
+        startedAt: Date.now(),
+    };
+}
+/** Total memory in bytes — used by telemetry + routing. */
+export function totalMemoryBytes() {
+    return totalmem();
+}

package/dist/kernel/federation/peer-mesh.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OpenKernel — Peer Mesh
+ *
+ * Tracks peers, keeps them alive with heartbeats, and (for peers we manage)
+ * holds an open SSE stream to receive their activity + telemetry. On heartbeat
+ * failure a peer is marked down and its stream reconnected — the self-healing
+ * that replaces a hand-rolled session scheduler.
+ *
+ * Connection direction honours the security model: WE open streams to peers we
+ * manage (satellites are accept-only). A satellite never dials us.
+ */
+import type { Logger } from '../types.js';
+import type { FederationEnvelope, NodeIdentity, PeerInfo, StreamFrame } from './types.js';
+import { MeshClient } from './transport-http.js';
+export interface PeerMeshOptions {
+    self: NodeIdentity;
+    client: MeshClient;
+    logger: Logger;
+    heartbeatMs?: number;
+    /** Frames streamed from a managed peer (activity, telemetry, heartbeat). */
+    onFrame: (peerId: string, frame: StreamFrame) => void;
+    /** Called whenever the peer set or a peer's connected state changes. */
+    onPeerChange?: () => void;
+    /** Current local load 0–100, sent with heartbeats. */
+    getLoad: () => number;
+}
+export declare class PeerMesh {
+    private opts;
+    private peers;
+    private streams;
+    private timer?;
+    private readonly hbMs;
+    constructor(opts: PeerMeshOptions);
+    list(): PeerInfo[];
+    get(nodeId: string): PeerInfo | undefined;
+    connected(): PeerInfo[];
+    /** Discover + attach a peer at a base URL (manifest probe + open its stream). */
+    connect(url: string): Promise<PeerInfo | null>;
+    private openStream;
+    start(): void;
+    private tick;
+    /** Upsert a peer we learned about via handshake (e.g. inbound hello). */
+    note(env: FederationEnvelope, url?: string): void;
+    remove(nodeId: string): void;
+    stop(): void;
+}

package/dist/kernel/federation/peer-mesh.js

@@ -0,0 +1,117 @@
+import { envelope } from './protocol.js';
+export class PeerMesh {
+    opts;
+    peers = new Map();
+    streams = new Map();
+    timer;
+    hbMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.hbMs = opts.heartbeatMs ?? 30_000;
+    }
+    list() {
+        return [...this.peers.values()];
+    }
+    get(nodeId) {
+        return this.peers.get(nodeId);
+    }
+    connected() {
+        return this.list().filter(p => p.connected);
+    }
+    /** Discover + attach a peer at a base URL (manifest probe + open its stream). */
+    async connect(url) {
+        try {
+            const manifest = await this.opts.client.fetchManifest(url);
+            const peer = {
+                nodeId: manifest.nodeId,
+                displayName: manifest.displayName,
+                role: manifest.role,
+                url,
+                connected: true,
+                lastSeenAt: Date.now(),
+                manifest,
+                version: manifest.version,
+            };
+            this.peers.set(peer.nodeId, peer);
+            this.openStream(peer);
+            this.opts.logger.info(`[federation] connected to ${peer.displayName} (${peer.nodeId}) @ ${url}`);
+            this.opts.onPeerChange?.();
+            return peer;
+        }
+        catch (err) {
+            this.opts.logger.warn(`[federation] connect failed ${url}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    openStream(peer) {
+        this.streams.get(peer.nodeId)?.(); // close any prior
+        const stop = this.opts.client.openStream(peer.url, f => {
+            peer.lastSeenAt = Date.now();
+            // Absorb telemetry frames into the peer record for routing.
+            if (f.t === 'hw' && f.d)
+                peer.hardware = f.d;
+            this.opts.onFrame(peer.nodeId, f);
+        }, () => {
+            // stream closed — heartbeat loop will attempt to revive
+            peer.connected = false;
+            this.opts.onPeerChange?.();
+        });
+        this.streams.set(peer.nodeId, stop);
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.tick(), this.hbMs);
+    }
+    async tick() {
+        await Promise.all(this.list().map(async (peer) => {
+            const t0 = Date.now();
+            try {
+                await this.opts.client.rpc(peer.url, envelope('heartbeat', this.opts.self.nodeId, { load: this.opts.getLoad() }, { to: peer.nodeId }));
+                peer.latencyMs = Date.now() - t0;
+                peer.lastSeenAt = Date.now();
+                if (!peer.connected) {
+                    peer.connected = true;
+                    this.openStream(peer); // revive stream after an outage
+                    this.opts.logger.info(`[federation] peer ${peer.displayName} back online`);
+                    this.opts.onPeerChange?.();
+                }
+            }
+            catch {
+                if (peer.connected) {
+                    peer.connected = false;
+                    this.streams.get(peer.nodeId)?.();
+                    this.streams.delete(peer.nodeId);
+                    this.opts.logger.warn(`[federation] peer ${peer.displayName} went offline`);
+                    this.opts.onPeerChange?.();
+                }
+            }
+        }));
+    }
+    /** Upsert a peer we learned about via handshake (e.g. inbound hello). */
+    note(env, url) {
+        const from = env.from;
+        const existing = this.peers.get(from);
+        if (existing) {
+            existing.lastSeenAt = Date.now();
+            return;
+        }
+        if (!url)
+            return;
+        void this.connect(url);
+    }
+    remove(nodeId) {
+        this.streams.get(nodeId)?.();
+        this.streams.delete(nodeId);
+        this.peers.delete(nodeId);
+        this.opts.onPeerChange?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        for (const stop of this.streams.values())
+            stop();
+        this.streams.clear();
+    }
+}

package/dist/kernel/federation/protocol.d.ts

@@ -0,0 +1,20 @@
+import { type FederationEnvelope, type MessageKind, type StreamFrame } from './types.js';
+export declare function newId(): string;
+export declare function envelope<T>(kind: MessageKind, from: string, data?: T, opts?: {
+    to?: string;
+    re?: string;
+    id?: string;
+    auth?: string;
+}): FederationEnvelope<T>;
+/** Build a reply envelope correlated to a request. */
+export declare function reply<T>(to: FederationEnvelope, kind: MessageKind, from: string, data?: T): FederationEnvelope<T>;
+export declare function nextSeq(): number;
+export declare function frame(t: StreamFrame['t'], from: string, d?: unknown): StreamFrame;
+/** Serialize a frame as an SSE `data:` block. Event name = frame type for
+ *  per-type handling on the harness side. */
+export declare function frameToSSE(f: StreamFrame): string;
+/** Parse a raw SSE chunk buffer into complete frames. Returns leftover text. */
+export declare function parseSSE(buffer: string): {
+    frames: StreamFrame[];
+    rest: string;
+};

package/dist/kernel/federation/protocol.js

@@ -0,0 +1,61 @@
+/**
+ * OpenKernel — Federation Protocol helpers
+ *
+ * Builders for the JSON envelope + the compact SSE stream frames. Keeping frame
+ * construction here means the transport, the event bridge, and the MOLTFED
+ * adapter all agree on one wire shape.
+ */
+import { nanoid } from 'nanoid';
+import { FEDERATION_PROTOCOL_VERSION, } from './types.js';
+export function newId() {
+    return nanoid(12);
+}
+export function envelope(kind, from, data, opts = {}) {
+    return {
+        v: FEDERATION_PROTOCOL_VERSION,
+        id: opts.id ?? newId(),
+        kind,
+        from,
+        to: opts.to,
+        re: opts.re,
+        ts: Date.now(),
+        auth: opts.auth,
+        data,
+    };
+}
+/** Build a reply envelope correlated to a request. */
+export function reply(to, kind, from, data) {
+    return envelope(kind, from, data, { to: to.from, re: to.id });
+}
+// ── Stream frames ────────────────────────────────────────────────────────────
+let seq = 0;
+export function nextSeq() {
+    seq = (seq + 1) % Number.MAX_SAFE_INTEGER;
+    return seq;
+}
+export function frame(t, from, d) {
+    return { t, n: from, s: nextSeq(), ts: Date.now(), d };
+}
+/** Serialize a frame as an SSE `data:` block. Event name = frame type for
+ *  per-type handling on the harness side. */
+export function frameToSSE(f) {
+    return `event: ${f.t}\ndata: ${JSON.stringify(f)}\n\n`;
+}
+/** Parse a raw SSE chunk buffer into complete frames. Returns leftover text. */
+export function parseSSE(buffer) {
+    const frames = [];
+    const parts = buffer.split('\n\n');
+    const rest = parts.pop() ?? '';
+    for (const block of parts) {
+        const dataLine = block.split('\n').find(l => l.startsWith('data:'));
+        if (!dataLine)
+            continue;
+        try {
+            frames.push(JSON.parse(dataLine.slice(5).trim()));
+        }
+        catch {
+            // skip malformed frame
+        }
+    }
+    return { frames, rest };
+}