@cueloop/daemon 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@cueloop/daemon",
+  "version": "0.1.0-alpha.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
+  },
+  "dependencies": {
+    "@cueloop/schema": "workspace:*",
+    "valibot": "^1.4.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/daemon"
+  }
+}

package/src/api.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonCore, verdictResponse } from "./api";
+import { SessionStore } from "./store";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = {
+  type: "plan",
+  content: "# Plan\n\n## Context\n\nDo the thing carefully.\n",
+  meta: { agent: "test-agent", planPath: "plan.md" },
+};
+
+let home: string;
+let core: DaemonCore;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-test-"));
+  core = new DaemonCore(home);
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+describe("session lifecycle", () => {
+  test("create → get → list", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    expect(s.status).toBe("pending");
+    expect(s.revisions.length).toBe(1);
+    expect(core.sessionGet(s.id).id).toBe(s.id);
+    expect(core.sessionList({ status: "pending" }).length).toBe(1);
+  });
+
+  test("annotate upserts by id; remove deletes", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionAnnotate(s.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "How carefully?",
+    });
+    core.sessionAnnotate(s.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "Define carefully.",
+    });
+    expect(core.sessionGet(s.id).annotations.length).toBe(1);
+    expect(core.sessionGet(s.id).annotations[0]!.body).toBe("Define carefully.");
+    core.sessionRemoveAnnotation(s.id, "a1");
+    expect(core.sessionGet(s.id).annotations.length).toBe(0);
+  });
+
+  test("resolve produces feedback.md and maps to the agent contract", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionAnnotate(s.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "Spell out the steps.",
+    });
+    const resolved = core.sessionResolve(s.id, "request_changes", "Needs detail.");
+    expect(resolved.verdict!.feedback).toContain("# Review: request changes");
+    expect(resolved.verdict!.feedback).toContain("> carefully");
+    expect(verdictResponse(resolved)).toEqual({ allow: false, feedback: resolved.verdict!.feedback });
+    const approved = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionResolve(approved.id, "approve", "LGTM");
+    expect(verdictResponse(core.sessionGet(approved.id)).allow).toBe(true);
+  });
+
+  test("mutating a resolved session throws", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionResolve(s.id, "approve", "");
+    expect(() =>
+      core.sessionAnnotate(s.id, { id: "a1", kind: "comment", anchor: { quote: "x", prefix: "", suffix: "" }, body: "b" }),
+    ).toThrow("already resolved");
+  });
+
+  test("working copy stores edits and clears on revert or no-op", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionSetWorkingCopy(s.id, PLAN.content.replace("carefully", "very carefully"));
+    expect(core.sessionGet(s.id).workingCopy).toContain("very carefully");
+    core.sessionSetWorkingCopy(s.id, PLAN.content);
+    expect(core.sessionGet(s.id).workingCopy).toBeUndefined();
+  });
+
+  test("revision reopens the session and resets working copy + verdict", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionSetWorkingCopy(s.id, PLAN.content + "\nedit");
+    core.sessionResolve(s.id, "request_changes", "redo");
+    const revised = core.sessionSubmitRevision(s.id, "# Plan v2\n");
+    expect(revised.status).toBe("pending");
+    expect(revised.verdict).toBeNull();
+    expect(revised.workingCopy).toBeUndefined();
+    expect(revised.revisions.length).toBe(2);
+    expect(revised.artifact.content).toBe("# Plan v2\n");
+  });
+});
+
+describe("the wait contract: verdicts outlive waits", () => {
+  test("wait resolves when the verdict arrives", async () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const wait = core.sessionWait(s.id, 5_000);
+    core.sessionResolve(s.id, "approve", "");
+    const resolved = await wait;
+    expect(resolved!.verdict!.kind).toBe("approve");
+  });
+
+  test("wait times out to null; a later wait collects the stored verdict", async () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const first = await core.sessionWait(s.id, 30);
+    expect(first).toBeNull();
+    core.sessionResolve(s.id, "request_changes", "later");
+    const second = await core.sessionWait(s.id, 30);
+    expect(second!.verdict!.summary).toBe("later");
+  });
+
+  test("multiple waiters all resolve", async () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const waits = [core.sessionWait(s.id, 5_000), core.sessionWait(s.id, 5_000)];
+    core.sessionResolve(s.id, "approve", "");
+    const results = await Promise.all(waits);
+    expect(results.every((r) => r?.status === "resolved")).toBe(true);
+  });
+});
+
+describe("persistence and recovery", () => {
+  test("sessions survive a daemon restart", () => {
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionResolve(s.id, "approve", "done");
+    const reborn = new DaemonCore(home);
+    const recovered = reborn.sessionGet(s.id);
+    expect(recovered.verdict!.summary).toBe("done");
+  });
+
+  test("corrupt records are skipped, not fatal, and never deleted", async () => {
+    core.sessionCreate({ workspace: WS, artifact: PLAN });
+    await Bun.write(join(home, "sessions", "broken.json"), "{ not json");
+    const store = new SessionStore(home);
+    const report = store.recover();
+    expect(report.recovered.length).toBe(1);
+    expect(report.skipped.length).toBe(1);
+    expect(await Bun.file(join(home, "sessions", "broken.json")).exists()).toBe(true);
+  });
+});
+
+describe("events", () => {
+  test("lifecycle events fire in order", () => {
+    const seen: string[] = [];
+    core.onEvent((e) => seen.push(e.event));
+    const s = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    core.sessionAnnotate(s.id, { id: "a1", kind: "comment", anchor: { quote: "thing", prefix: "", suffix: "" }, body: "b" });
+    core.sessionResolve(s.id, "approve", "");
+    expect(seen).toEqual(["session.created", "inbox.changed", "session.updated", "session.resolved", "inbox.changed"]);
+  });
+});

package/src/api.ts

@@ -0,0 +1,200 @@
+/**
+ * The daemon's method surface (#14). Transport-independent: the socket
+ * server and the in-process test harness both call these handlers.
+ * The wait contract: verdicts outlive waits - session.wait long-polls,
+ * and a verdict resolved while nobody waited is delivered on next contact.
+ */
+
+import {
+  SCHEMA_VERSION,
+  feedbackForSession,
+  verdictAllows,
+  type Annotation,
+  type Artifact,
+  type ReviewSession,
+  type Verdict,
+  type VerdictKind,
+  type WorkspaceKey,
+} from "@cueloop/schema";
+import { SessionStore } from "./store";
+import { DaemonError } from "./errors";
+
+export type EventName =
+  | "session.created"
+  | "session.updated"
+  | "session.resolved"
+  | "session.revised"
+  | "inbox.changed";
+
+export interface DaemonEvent {
+  event: EventName;
+  sessionId: string;
+}
+
+type EventListener = (e: DaemonEvent) => void;
+
+export class DaemonCore {
+  readonly store: SessionStore;
+  private waiters = new Map<string, ((session: ReviewSession) => void)[]>();
+  private listeners = new Set<EventListener>();
+  private seq = 0;
+
+  constructor(home: string) {
+    this.store = new SessionStore(home);
+    this.store.recover();
+  }
+
+  onEvent(listener: EventListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(event: EventName, sessionId: string): void {
+    for (const l of this.listeners) l({ event, sessionId });
+  }
+
+  /** True when nothing awaits a verdict - drives idle-exit. */
+  hasPendingSessions(): boolean {
+    return this.store.list().some((s) => s.status === "pending");
+  }
+
+  sessionCreate(params: { workspace: WorkspaceKey; artifact: Artifact }): ReviewSession {
+    const now = new Date().toISOString();
+    const session: ReviewSession = {
+      schemaVersion: SCHEMA_VERSION,
+      id: `ses_${now.replace(/\D/g, "").slice(0, 14)}_${(++this.seq).toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+      workspace: params.workspace,
+      artifact: params.artifact,
+      revisions: [{ revision: 1, content: params.artifact.content, submittedAt: now }],
+      annotations: [],
+      verdict: null,
+      status: "pending",
+      createdAt: now,
+    };
+    this.store.upsert(session);
+    this.emit("session.created", session.id);
+    this.emit("inbox.changed", session.id);
+    return session;
+  }
+
+  sessionGet(id: string): ReviewSession {
+    const s = this.store.get(id);
+    if (!s) throw new DaemonError("not_found", `no session ${id}`);
+    return s;
+  }
+
+  sessionList(filter?: { status?: "pending" | "resolved"; workspace?: Partial<WorkspaceKey> }): ReviewSession[] {
+    return this.store.list().filter((s) => {
+      if (filter?.status && s.status !== filter.status) return false;
+      if (filter?.workspace?.repoRoot && s.workspace.repoRoot !== filter.workspace.repoRoot) return false;
+      if (filter?.workspace?.branch && s.workspace.branch !== filter.workspace.branch) return false;
+      return true;
+    });
+  }
+
+  /**
+   * Long-poll for the verdict. Resolves immediately when already resolved;
+   * otherwise parks until sessionResolve fires or timeoutMs elapses (null =
+   * still pending - the caller re-polls later; the verdict is never lost).
+   */
+  sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
+    const s = this.sessionGet(id);
+    if (s.status === "resolved") return Promise.resolve(s);
+    return new Promise((resolve) => {
+      const list = this.waiters.get(id) ?? [];
+      let done = false;
+      const timer = setTimeout(() => {
+        if (done) return;
+        done = true;
+        const idx = list.indexOf(waiter);
+        if (idx !== -1) list.splice(idx, 1);
+        resolve(null);
+      }, timeoutMs);
+      const waiter = (session: ReviewSession) => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        resolve(session);
+      };
+      list.push(waiter);
+      this.waiters.set(id, list);
+    });
+  }
+
+  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): ReviewSession {
+    const s = this.mutable(id);
+    const existing = s.annotations.findIndex((a) => a.id === annotation.id);
+    const full: Annotation = { ...annotation, createdAt: new Date().toISOString() };
+    if (existing === -1) s.annotations.push(full);
+    else s.annotations[existing] = { ...full, createdAt: s.annotations[existing]!.createdAt };
+    this.store.upsert(s);
+    this.emit("session.updated", id);
+    return s;
+  }
+
+  sessionRemoveAnnotation(id: string, annotationId: string): ReviewSession {
+    const s = this.mutable(id);
+    s.annotations = s.annotations.filter((a) => a.id !== annotationId);
+    this.store.upsert(s);
+    this.emit("session.updated", id);
+    return s;
+  }
+
+  /** The reviewer's working copy; undefined clears it (revert all edits). */
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): ReviewSession {
+    const s = this.mutable(id);
+    if (workingCopy === undefined || workingCopy === s.artifact.content) delete s.workingCopy;
+    else s.workingCopy = workingCopy;
+    this.store.upsert(s);
+    this.emit("session.updated", id);
+    return s;
+  }
+
+  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): ReviewSession {
+    const s = this.mutable(id);
+    const verdict: Verdict = {
+      kind: verdictKind,
+      summary,
+      feedback: feedbackForSession(s, verdictKind, summary),
+      resolvedAt: new Date().toISOString(),
+    };
+    s.verdict = verdict;
+    s.status = "resolved";
+    this.store.upsert(s);
+    const parked = this.waiters.get(id) ?? [];
+    this.waiters.delete(id);
+    for (const w of parked) w(s);
+    this.emit("session.resolved", id);
+    this.emit("inbox.changed", id);
+    return s;
+  }
+
+  /** Agent resubmits: new revision becomes the artifact, session reopens. */
+  sessionSubmitRevision(id: string, content: string): ReviewSession {
+    const s = this.sessionGet(id);
+    const now = new Date().toISOString();
+    s.revisions.push({ revision: s.revisions.length + 1, content, submittedAt: now });
+    s.artifact = { ...s.artifact, content };
+    delete s.workingCopy;
+    s.verdict = null;
+    s.status = "pending";
+    this.store.upsert(s);
+    this.emit("session.revised", id);
+    this.emit("inbox.changed", id);
+    return s;
+  }
+
+  private mutable(id: string): ReviewSession {
+    const s = this.sessionGet(id);
+    if (s.status === "resolved") throw new DaemonError("resolved", `session ${id} is already resolved`);
+    return s;
+  }
+}
+
+export { DaemonError };
+
+/** Convenience for adapters: map a resolved session to the agent contract. */
+export function verdictResponse(session: ReviewSession): { allow: boolean; feedback: string } {
+  if (!session.verdict) throw new DaemonError("pending", "session has no verdict");
+  return { allow: verdictAllows(session.verdict.kind), feedback: session.verdict.feedback };
+}

package/src/client.ts

@@ -0,0 +1,183 @@
+/**
+ * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
+ * adapters, and tests. Also owns the lazy-launch story (#14): connect() with
+ * autostart spawns a detached daemon when the socket is dead, then attaches.
+ */
+
+import { existsSync, rmSync } from "node:fs";
+import type { Annotation, Artifact, ReviewSession, VerdictKind, WorkspaceKey } from "@cueloop/schema";
+import { LineBuffer, type EventFrame, type Response } from "./protocol";
+import { cueloopHome, socketPath } from "./paths";
+
+export interface ConnectOptions {
+  home?: string;
+  /** Spawn the daemon when the socket is not alive. */
+  autostart?: boolean;
+}
+
+type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void };
+
+export class DaemonClient {
+  private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
+  private pending = new Map<number, Pending>();
+  private nextId = 1;
+  private eventListeners = new Set<(e: EventFrame) => void>();
+  private closed = false;
+
+  static async connect(opts: ConnectOptions = {}): Promise<DaemonClient> {
+    const home = opts.home ?? cueloopHome();
+    const path = socketPath(home);
+    const client = new DaemonClient();
+    try {
+      await client.dial(path);
+      return client;
+    } catch (err) {
+      if (!opts.autostart) throw err;
+    }
+    // Socket dead or absent: clean a stale file and spawn the daemon detached.
+    if (existsSync(path)) rmSync(path, { force: true });
+    spawnDaemon(home);
+    // Generous: a cold or loaded machine pays for a runtime start before the
+    // socket exists, and giving up early looks to callers like a broken daemon.
+    const deadline = Date.now() + Number(process.env.CUELOOP_START_TIMEOUT_MS ?? 30_000);
+    let lastErr: unknown;
+    while (Date.now() < deadline) {
+      try {
+        await client.dial(path);
+        return client;
+      } catch (err) {
+        lastErr = err;
+        await Bun.sleep(50);
+      }
+    }
+    throw new Error(`daemon did not come up at ${path}: ${String(lastErr)}`);
+  }
+
+  private async dial(path: string): Promise<void> {
+    const buffer = new LineBuffer();
+    const self = this;
+    this.socket = await Bun.connect({
+      unix: path,
+      socket: {
+        data(_socket, data) {
+          buffer.push(data.toString(), (line) => self.handleFrame(line));
+        },
+        close() {
+          self.closed = true;
+          for (const p of self.pending.values()) p.reject(new Error("daemon connection closed"));
+          self.pending.clear();
+        },
+        error() {},
+      },
+    });
+    // Verify liveness: a dead socket file accepts connects on some platforms
+    // only to fail later, so a ping is the actual handshake.
+    await this.request("daemon.ping", {}, 2_000);
+  }
+
+  onEvent(listener: (e: EventFrame) => void): () => void {
+    this.eventListeners.add(listener);
+    return () => this.eventListeners.delete(listener);
+  }
+
+  private handleFrame(line: string): void {
+    let frame: Response | EventFrame;
+    try {
+      frame = JSON.parse(line) as Response | EventFrame;
+    } catch {
+      return;
+    }
+    if ("event" in frame) {
+      for (const l of this.eventListeners) l(frame);
+      return;
+    }
+    const p = this.pending.get(frame.id);
+    if (!p) return;
+    this.pending.delete(frame.id);
+    if (frame.error) p.reject(new DaemonClientError(frame.error.code, frame.error.message));
+    else p.resolve(frame.result);
+  }
+
+  request<T = unknown>(method: string, params: unknown, timeoutMs = 30_000): Promise<T> {
+    if (this.closed || !this.socket) return Promise.reject(new Error("not connected"));
+    const id = this.nextId++;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`request ${method} timed out`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v as T);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+      this.socket!.write(JSON.stringify({ id, method, params }) + "\n");
+    });
+  }
+
+  close(): void {
+    this.closed = true;
+    this.socket?.end();
+  }
+
+  // ── typed verbs ─────────────────────────────
+  ping(): Promise<{ pid: number }> {
+    return this.request("daemon.ping", {});
+  }
+  subscribe(): Promise<void> {
+    return this.request("events.subscribe", {});
+  }
+  sessionCreate(workspace: WorkspaceKey, artifact: Artifact): Promise<ReviewSession> {
+    return this.request("session.create", { workspace, artifact });
+  }
+  sessionGet(id: string): Promise<ReviewSession> {
+    return this.request("session.get", { id });
+  }
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<ReviewSession[]> {
+    return this.request("session.list", { filter });
+  }
+  /** Long-poll; null = still pending after timeoutMs (re-poll to collect). */
+  sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
+    return this.request("session.wait", { id, timeoutMs }, timeoutMs + 10_000);
+  }
+  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession> {
+    return this.request("session.annotate", { id, annotation });
+  }
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession> {
+    return this.request("session.removeAnnotation", { id, annotationId });
+  }
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
+    return this.request("session.setWorkingCopy", { id, workingCopy });
+  }
+  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
+    return this.request("session.resolve", { id, verdictKind, summary });
+  }
+  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
+    return this.request("session.submitRevision", { id, content });
+  }
+  shutdown(): Promise<void> {
+    return this.request("daemon.shutdown", {});
+  }
+}
+
+export class DaemonClientError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function spawnDaemon(home: string): void {
+  const entry = new URL("./main.ts", import.meta.url).pathname;
+  Bun.spawn([process.execPath, "run", entry], {
+    env: { ...process.env, CUELOOP_HOME: home },
+    stdio: ["ignore", "ignore", "ignore"],
+  }).unref();
+}

package/src/errors.ts

@@ -0,0 +1,10 @@
+/** Daemon errors carry a stable code so clients can branch on it. */
+
+export class DaemonError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./api";
+export * from "./errors";
+export * from "./validate";
+export * from "./store";
+export * from "./server";
+export * from "./protocol";
+export * from "./paths";
+export { DaemonClient, DaemonClientError, type ConnectOptions } from "./client";

package/src/main.ts

@@ -0,0 +1,22 @@
+/** Daemon entry point: run detached by DaemonClient.connect({autostart}). */
+
+import { DaemonServer } from "./server";
+
+const idleExitMs = process.env.CUELOOP_IDLE_EXIT_MS ? Number(process.env.CUELOOP_IDLE_EXIT_MS) : undefined;
+const server = new DaemonServer({ idleExitMs });
+const path = server.start();
+if (path === null) {
+  // another daemon already owns this home; the client will attach to it
+  console.log("cueloop daemon already running for this home");
+  process.exit(0);
+}
+console.log(`cueloop daemon listening on ${path}`);
+
+process.on("SIGINT", () => {
+  server.stop();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  server.stop();
+  process.exit(0);
+});

package/src/paths.ts

@@ -0,0 +1,27 @@
+/**
+ * State-dir resolution. Everything the daemon persists lives under one home
+ * directory; tests point CUELOOP_HOME at a temp dir to get full isolation.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export function cueloopHome(): string {
+  return process.env.CUELOOP_HOME ?? join(homedir(), ".cueloop");
+}
+
+export function socketPath(home = cueloopHome()): string {
+  return join(home, "cueloop.sock");
+}
+
+export function sessionsDir(home = cueloopHome()): string {
+  return join(home, "sessions");
+}
+
+export function pidPath(home = cueloopHome()): string {
+  return join(home, "cueloop.pid");
+}
+
+export function lockPath(home = cueloopHome()): string {
+  return join(home, "cueloop.lock");
+}

package/src/protocol.ts

@@ -0,0 +1,40 @@
+/**
+ * Wire protocol (#14): newline-delimited JSON over the unix socket.
+ * Requests: { id, method, params }  Responses: { id, result } | { id, error }
+ * Events (push, after events.subscribe): { event, sessionId }
+ */
+
+export interface Request {
+  id: number;
+  method: string;
+  params?: unknown;
+}
+
+export interface Response {
+  id: number;
+  result?: unknown;
+  error?: { code: string; message: string };
+}
+
+export interface EventFrame {
+  event: string;
+  sessionId: string;
+}
+
+export type Frame = Response | EventFrame;
+
+/** Incremental NDJSON splitter; tolerates partial writes. */
+export class LineBuffer {
+  private buf = "";
+
+  push(chunk: string, onLine: (line: string) => void): void {
+    this.buf += chunk;
+    for (;;) {
+      const nl = this.buf.indexOf("\n");
+      if (nl === -1) return;
+      const line = this.buf.slice(0, nl).trim();
+      this.buf = this.buf.slice(nl + 1);
+      if (line) onLine(line);
+    }
+  }
+}