@syengup/friday-channel-next 0.0.1

package/src/sse/emitter.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+import { sseEmitter } from "./emitter.js";
+import { setOfflineQueueBaseDirForTest } from "./offline-queue.js";
+
+class MockRes extends EventEmitter {
+  writes: string[] = [];
+  write(chunk: string): boolean {
+    this.writes.push(chunk);
+    return true;
+  }
+  end(): void {
+    // no-op
+  }
+}
+
+describe("sseEmitter", () => {
+  let tmp = "";
+
+  beforeEach(() => {
+    sseEmitter.resetForTest();
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "friday-sse-emit-"));
+    setOfflineQueueBaseDirForTest(tmp);
+  });
+
+  afterEach(() => {
+    setOfflineQueueBaseDirForTest(null);
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it("tracks run-to-device mapping", () => {
+    sseEmitter.trackDeviceForRun("device-a", "run-a");
+    expect(sseEmitter.getDeviceIdByRunId("run-a")).toBe("DEVICE-A");
+    expect(sseEmitter.getLastRunIdForDevice("device-a")).toBe("run-a");
+    expect(sseEmitter.hasTrackedDevices("run-a")).toBe(true);
+    sseEmitter.untrackRun("run-a");
+    expect(sseEmitter.hasTrackedDevices("run-a")).toBe(false);
+  });
+
+  it("uses per-device event id sequence", () => {
+    const a = new MockRes();
+    const b = new MockRes();
+    sseEmitter.addConnection("device-a-seq", a as never);
+    sseEmitter.addConnection("device-b-seq", b as never);
+
+    sseEmitter.broadcast({ type: "agent", data: { text: "1" } }, "device-a-seq", true);
+    sseEmitter.broadcast({ type: "agent", data: { text: "2" } }, "device-a-seq", true);
+    sseEmitter.broadcast({ type: "agent", data: { text: "x" } }, "device-b-seq", true);
+
+    const aw = a.writes.join("");
+    const bw = b.writes.join("");
+    expect(aw).toContain("id: 1");
+    expect(aw).toContain("id: 2");
+    expect(bw).toContain("id: 1");
+
+    sseEmitter.removeConnection("device-a-seq");
+    sseEmitter.removeConnection("device-b-seq");
+  });
+
+  it("replays only entries after last event id from disk", () => {
+    const c = new MockRes();
+    sseEmitter.addConnection("device-replay", c as never);
+    sseEmitter.setBacklogLimit(50);
+    sseEmitter.broadcast({ type: "agent", data: { text: "a" } }, "device-replay", true);
+    sseEmitter.broadcast({ type: "agent", data: { text: "b" } }, "device-replay", true);
+    sseEmitter.broadcast({ type: "agent", data: { text: "c" } }, "device-replay", true);
+
+    c.writes = [];
+    const replayed = sseEmitter.replayBacklog("device-replay", 1);
+    expect(replayed).toBe(2);
+    const body = c.writes.join("");
+    expect(body).toContain("id: 2");
+    expect(body).toContain("id: 3");
+    expect(body).not.toContain("text\":\"a\"");
+
+    sseEmitter.removeConnection("device-replay");
+  });
+});

package/src/sse/emitter.ts

@@ -0,0 +1,249 @@
+import type { ServerResponse } from "node:http";
+import { createFridayNextLogger } from "../logging.js";
+import { fridaySseOfflineQueue } from "./offline-queue.js";
+
+const logger = createFridayNextLogger("sse", "info");
+
+export type SseEventType = "connected" | "agent" | "deliver" | "tool-hook" | "outbound" | "ping";
+
+export interface SseEvent {
+  type: SseEventType;
+  data: Record<string, unknown>;
+}
+
+type BacklogEntry = {
+  id: number;
+  event: SseEvent;
+};
+
+export class SseConnection {
+  readonly deviceId: string;
+  private readonly res: ServerResponse;
+  private closed = false;
+  private pending: string[] = [];
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private waitingDrain = false;
+
+  constructor(deviceId: string, res: ServerResponse) {
+    this.deviceId = deviceId;
+    this.res = res;
+    this.res.on("drain", () => {
+      this.waitingDrain = false;
+      this.scheduleFlush();
+    });
+    this.res.on("error", () => this.close());
+  }
+
+  send(entry: BacklogEntry | SseEvent, flushNow?: boolean): void {
+    if (this.closed) return;
+    const normalized =
+      "id" in entry && "event" in entry ? entry : { id: Date.now(), event: entry as SseEvent };
+    const payload = JSON.stringify(normalized.event.data);
+    this.pending.push(
+      `id: ${normalized.id}\nevent: ${normalized.event.type}\ndata: ${payload}\n\n`,
+    );
+    if (flushNow) {
+      if (this.flushTimer) clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+      this.flush();
+      return;
+    }
+    this.scheduleFlush();
+  }
+
+  sendRaw(line: string): void {
+    if (this.closed) return;
+    const ok = this.res.write(line);
+    if (ok === false) this.waitingDrain = true;
+  }
+
+  private scheduleFlush(): void {
+    if (this.waitingDrain || this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flush();
+    }, 16);
+  }
+
+  private flush(): void {
+    if (this.closed || this.waitingDrain || this.pending.length === 0) return;
+    const data = this.pending.join("");
+    this.pending = [];
+    const ok = this.res.write(data);
+    if (ok === false) this.waitingDrain = true;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+    this.pending = [];
+    try {
+      this.res.end();
+    } catch {
+      // ignore
+    }
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+}
+
+class SseEmitterRegistry {
+  private connections = new Map<string, SseConnection>();
+  private runEmitter = new Map<string, Set<string>>();
+  private lastRunIdByDevice = new Map<string, string>();
+  private eventSeqByDevice = new Map<string, number>();
+  private backlogLimit = 200;
+
+  getConnectionCount(): number {
+    return this.connections.size;
+  }
+
+  setBacklogLimit(limit: number): void {
+    this.backlogLimit = Math.max(0, Math.floor(limit));
+  }
+
+  getBacklogLimit(): number {
+    return this.backlogLimit;
+  }
+
+  /** Last persisted / assigned SSE id for device (for `connected.lastSeq`). */
+  latestSeqForDevice(deviceId: string): number {
+    const key = deviceId.trim().toUpperCase();
+    const disk = fridaySseOfflineQueue.latestId(key);
+    const mem = this.eventSeqByDevice.get(key) ?? 0;
+    return Math.max(disk, mem);
+  }
+
+  addConnection(deviceId: string, res: ServerResponse): SseConnection {
+    const normalized = deviceId.trim().toUpperCase();
+    const existing = this.connections.get(normalized);
+    if (existing && !existing.isClosed) {
+      existing.close();
+      for (const set of this.runEmitter.values()) {
+        set.delete(normalized);
+      }
+    }
+    const conn = new SseConnection(normalized, res);
+    this.connections.set(normalized, conn);
+    logger.info(`connect ${normalized} total=${this.connections.size}`);
+    return conn;
+  }
+
+  /**
+   * @param expectedConn When provided, only removes if this connection is still the active one
+   * (avoids stale `req.close` after a reconnect replaced the map entry).
+   */
+  removeConnection(deviceId: string, expectedConn?: SseConnection): void {
+    const normalized = deviceId.trim().toUpperCase();
+    const current = this.connections.get(normalized);
+    if (expectedConn !== undefined && current !== expectedConn) {
+      return;
+    }
+    current?.close();
+    this.connections.delete(normalized);
+    for (const set of this.runEmitter.values()) set.delete(normalized);
+    logger.info(`disconnect ${normalized} total=${this.connections.size}`);
+  }
+
+  getConnection(deviceId: string): SseConnection | undefined {
+    return this.connections.get(deviceId.trim().toUpperCase());
+  }
+
+  private nextEntry(deviceId: string, event: SseEvent): BacklogEntry {
+    const key = deviceId.trim().toUpperCase();
+    const diskMax = fridaySseOfflineQueue.latestId(key);
+    const memMax = this.eventSeqByDevice.get(key) ?? 0;
+    const last = Math.max(memMax, diskMax);
+    const id = last + 1;
+    this.eventSeqByDevice.set(key, id);
+    fridaySseOfflineQueue.append(key, id, event.type, event.data, this.backlogLimit);
+    return { id, event };
+  }
+
+  replayBacklog(deviceId: string, afterEventId: number): number {
+    const key = deviceId.trim().toUpperCase();
+    const conn = this.connections.get(key);
+    if (!conn) return 0;
+    const entries = fridaySseOfflineQueue.readAfter(key, afterEventId);
+    let count = 0;
+    for (const e of entries) {
+      conn.send({ id: e.id, event: { type: e.event as SseEventType, data: e.data } }, true);
+      count += 1;
+    }
+    return count;
+  }
+
+  broadcast(event: SseEvent, deviceId?: string, flushNow?: boolean): void {
+    if (deviceId) {
+      const key = deviceId.trim().toUpperCase();
+      const entry = this.nextEntry(key, event);
+      this.connections.get(key)?.send(entry, flushNow);
+      return;
+    }
+    for (const conn of this.connections.values()) {
+      const entry = this.nextEntry(conn.deviceId, event);
+      conn.send(entry, flushNow);
+    }
+  }
+
+  trackDeviceForRun(deviceId: string, runId: string): void {
+    const key = deviceId.trim().toUpperCase();
+    const set = this.runEmitter.get(runId) ?? new Set<string>();
+    set.add(key);
+    this.runEmitter.set(runId, set);
+    this.lastRunIdByDevice.set(key, runId);
+  }
+
+  untrackRun(runId: string): void {
+    this.runEmitter.delete(runId);
+  }
+
+  hasTrackedDevices(runId: string): boolean {
+    return (this.runEmitter.get(runId)?.size ?? 0) > 0;
+  }
+
+  getDeviceIdByRunId(runId: string): string | null {
+    const first = this.runEmitter.get(runId)?.values().next().value;
+    return typeof first === "string" ? first : null;
+  }
+
+  getSoleConnectedDeviceId(): string | null {
+    if (this.connections.size !== 1) return null;
+    return this.connections.keys().next().value ?? null;
+  }
+
+  getLastRunIdForDevice(deviceId: string): string | null {
+    return this.lastRunIdByDevice.get(deviceId.trim().toUpperCase()) ?? null;
+  }
+
+  broadcastToRun(runId: string, event: SseEvent, flushNow?: boolean): void {
+    const direct = typeof event.data.deviceId === "string" ? event.data.deviceId : "";
+    if (direct.trim()) {
+      this.broadcast(event, direct, flushNow);
+      return;
+    }
+    const set = this.runEmitter.get(runId);
+    if (!set || set.size === 0) return;
+    for (const deviceId of set) this.broadcast(event, deviceId, flushNow);
+  }
+
+  broadcastToolEvent(deviceId: string, runId: string, event: SseEvent, flushNow?: boolean): void {
+    this.trackDeviceForRun(deviceId, runId);
+    this.broadcastToRun(runId, event, flushNow ?? true);
+  }
+
+  /** Vitest / e2e: drop connections and in-memory seq maps (does not delete disk queue files). */
+  resetForTest(): void {
+    for (const c of this.connections.values()) c.close();
+    this.connections.clear();
+    this.runEmitter.clear();
+    this.lastRunIdByDevice.clear();
+    this.eventSeqByDevice.clear();
+  }
+}
+
+export const sseEmitter = new SseEmitterRegistry();

package/src/sse/frame-format.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+import { sseEmitter } from "./emitter.js";
+import { setOfflineQueueBaseDirForTest } from "./offline-queue.js";
+
+class MockRes extends EventEmitter {
+  writes: string[] = [];
+  write(chunk: string): boolean {
+    this.writes.push(chunk);
+    return true;
+  }
+  end(): void {
+    // no-op
+  }
+}
+
+describe("sse frame format", () => {
+  let tmp = "";
+
+  beforeEach(() => {
+    sseEmitter.resetForTest();
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "friday-frame-"));
+    setOfflineQueueBaseDirForTest(tmp);
+  });
+
+  afterEach(() => {
+    setOfflineQueueBaseDirForTest(null);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("emits id/event/data with raw JSON payload", () => {
+    const res = new MockRes();
+    sseEmitter.addConnection("frame-device", res as never);
+
+    sseEmitter.broadcast(
+      {
+        type: "agent",
+        data: { runId: "r1", stream: "assistant", text: "hello" },
+      },
+      "frame-device",
+      true,
+    );
+
+    const frame = res.writes.join("");
+    expect(frame).toContain("id: 1\n");
+    expect(frame).toContain("event: agent\n");
+    expect(frame).toContain('"runId":"r1"');
+    expect(frame).toContain('"stream":"assistant"');
+    expect(frame).toContain('"text":"hello"');
+
+    sseEmitter.removeConnection("frame-device");
+  });
+});

package/src/sse/offline-queue.test.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { FridaySseOfflineQueue, setOfflineQueueBaseDirForTest } from "./offline-queue.js";
+
+describe("FridaySseOfflineQueue", () => {
+  let tmp = "";
+
+  afterEach(() => {
+    setOfflineQueueBaseDirForTest(null);
+    if (tmp) {
+      try {
+        fs.rmSync(tmp, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+      tmp = "";
+    }
+  });
+
+  it("append / readAfter / latestId", () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "friday-q-"));
+    setOfflineQueueBaseDirForTest(tmp);
+    const q = new FridaySseOfflineQueue(tmp);
+    expect(q.latestId("dev-a")).toBe(0);
+    q.append("dev-a", 1, "agent", { x: 1 }, 100);
+    q.append("dev-a", 2, "deliver", { y: 2 }, 100);
+    expect(q.latestId("dev-a")).toBe(2);
+    expect(q.readAfter("dev-a", 0).map((e) => e.id)).toEqual([1, 2]);
+    expect(q.readAfter("dev-a", 1).map((e) => e.id)).toEqual([2]);
+  });
+
+  it("does not persist connected", () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "friday-q-"));
+    setOfflineQueueBaseDirForTest(tmp);
+    const q = new FridaySseOfflineQueue(tmp);
+    q.append("dev-b", 1, "connected", { ok: true }, 100);
+    expect(q.readAfter("dev-b", 0)).toEqual([]);
+    expect(q.latestId("dev-b")).toBe(0);
+  });
+
+  it("truncateKeepLastN drops oldest", () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "friday-q-"));
+    setOfflineQueueBaseDirForTest(tmp);
+    const q = new FridaySseOfflineQueue(tmp);
+    for (let i = 1; i <= 5; i++) {
+      q.append("dev-c", i, "agent", { i }, 0);
+    }
+    q.truncateKeepLastN("dev-c", 2);
+    const rest = q.readAfter("dev-c", 0);
+    expect(rest.map((e) => e.id)).toEqual([4, 5]);
+  });
+
+  it("append with backlogLimit truncates", () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "friday-q-"));
+    setOfflineQueueBaseDirForTest(tmp);
+    const q = new FridaySseOfflineQueue(tmp);
+    for (let i = 1; i <= 4; i++) {
+      q.append("dev-d", i, "agent", { i }, 2);
+    }
+    const rest = q.readAfter("dev-d", 0);
+    expect(rest.map((e) => e.id)).toEqual([3, 4]);
+  });
+});

package/src/sse/offline-queue.ts

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveFridayNextConfig } from "../config.js";
+import { getHostOpenClawConfigSnapshot } from "../host-config.js";
+import { getFridayNextRuntime } from "../runtime.js";
+
+export type PersistedSseEntry = {
+  id: number;
+  event: string;
+  data: Record<string, unknown>;
+};
+
+/** Test-only override for queue base directory. */
+let testQueueBaseDir: string | null = null;
+
+export function setOfflineQueueBaseDirForTest(dir: string | null): void {
+  testQueueBaseDir = dir;
+}
+
+export function resolveFridayNextEventsQueueDir(): string {
+  if (testQueueBaseDir) return testQueueBaseDir;
+  try {
+    const cfg = resolveFridayNextConfig(getHostOpenClawConfigSnapshot(getFridayNextRuntime().config));
+    return path.join(path.dirname(cfg.historyDir), "events-queue");
+  } catch {
+    return path.join(os.homedir(), ".openclaw", "friday-next", "events-queue");
+  }
+}
+
+/**
+ * Per-device JSONL persistence for SSE replay.
+ * `overrideBaseDir` is for tests; production uses `resolveFridayNextEventsQueueDir()`.
+ */
+export class FridaySseOfflineQueue {
+  constructor(private readonly overrideBaseDir: string | null = null) {}
+
+  private baseDir(): string {
+    if (this.overrideBaseDir) return this.overrideBaseDir;
+    return resolveFridayNextEventsQueueDir();
+  }
+
+  private devicePath(deviceId: string): string {
+    const key = deviceId.trim().toUpperCase();
+    return path.join(this.baseDir(), `${key}.jsonl`);
+  }
+
+  private ensureDir(): void {
+    fs.mkdirSync(this.baseDir(), { recursive: true });
+  }
+
+  /** Highest id in file (full scan; ok for bounded backlog). */
+  scanMaxId(deviceId: string): number {
+    const file = this.devicePath(deviceId);
+    if (!fs.existsSync(file)) return 0;
+    let max = 0;
+    const content = fs.readFileSync(file, "utf8");
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const o = JSON.parse(line) as { id?: number };
+        if (typeof o.id === "number" && o.id > max) max = o.id;
+      } catch {
+        /* skip corrupt line */
+      }
+    }
+    return max;
+  }
+
+  latestId(deviceId: string): number {
+    return this.scanMaxId(deviceId.trim().toUpperCase());
+  }
+
+  append(deviceId: string, id: number, event: string, data: Record<string, unknown>, backlogLimit: number): void {
+    if (event === "connected") return;
+    this.ensureDir();
+    const file = this.devicePath(deviceId);
+    const line = JSON.stringify({ id, event, data } satisfies PersistedSseEntry) + "\n";
+    fs.appendFileSync(file, line, "utf8");
+    if (backlogLimit > 0) {
+      this.truncateKeepLastN(deviceId, backlogLimit);
+    }
+  }
+
+  readAfter(deviceId: string, afterId: number): PersistedSseEntry[] {
+    const file = this.devicePath(deviceId);
+    if (!fs.existsSync(file)) return [];
+    const out: PersistedSseEntry[] = [];
+    const content = fs.readFileSync(file, "utf8");
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const o = JSON.parse(line) as PersistedSseEntry;
+        if (
+          typeof o.id === "number" &&
+          o.id > afterId &&
+          typeof o.event === "string" &&
+          o.data &&
+          typeof o.data === "object" &&
+          !Array.isArray(o.data)
+        ) {
+          out.push(o);
+        }
+      } catch {
+        /* skip */
+      }
+    }
+    out.sort((a, b) => a.id - b.id);
+    return out;
+  }
+
+  truncateKeepLastN(deviceId: string, keep: number): void {
+    if (keep <= 0) return;
+    const file = this.devicePath(deviceId);
+    if (!fs.existsSync(file)) return;
+    const all: PersistedSseEntry[] = [];
+    const content = fs.readFileSync(file, "utf8");
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const o = JSON.parse(line) as PersistedSseEntry;
+        if (typeof o.id === "number" && typeof o.event === "string" && o.data && typeof o.data === "object") {
+          all.push(o);
+        }
+      } catch {
+        /* skip */
+      }
+    }
+    if (all.length <= keep) return;
+    const slice = all.slice(-keep);
+    fs.writeFileSync(
+      file,
+      slice.map((e) => JSON.stringify(e) + "\n").join(""),
+      "utf8",
+    );
+  }
+}
+
+/** Shared queue: base directory follows `setOfflineQueueBaseDirForTest` / config. */
+export const fridaySseOfflineQueue = new FridaySseOfflineQueue(null);