meridian-sdk 1.0.1 → 1.2.0

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   LwwRegisterSnapshotEntry,
   PresenceSnapshotEntry,
   CRDTMapSnapshotEntry,
+  RGASnapshotEntry,
 } from "./client.js";
 
 // CRDT handles
@@ -25,10 +26,11 @@ export { CRDTMapHandle } from "./crdt/crdtmap.js";
 export type { CrdtMapValue } from "./crdt/crdtmap.js";
 export { AwarenessHandle } from "./crdt/awareness.js";
 export type { AwarenessEntry } from "./crdt/awareness.js";
+export { RGAHandle } from "./crdt/rga.js";
 
 // Transport
 export { HttpClient } from "./transport/http.js";
-export type { HttpClientConfig } from "./transport/http.js";
+export type { HttpClientConfig, HistoryEntry, HistoryResponse } from "./transport/http.js";
 export { WsTransport } from "./transport/websocket.js";
 export type { WsTransportConfig, WsState } from "./transport/websocket.js";
 
@@ -63,6 +65,20 @@ export {
 } from "./schema.js";
 export type { TimestampMs, ClientId } from "./schema.js";
 
+// AI Agents — Claude tool use helpers
+export {
+  getMeridianTools,
+  executeMeridianTool,
+} from "./agents.js";
+export type {
+  Tool,
+  ToolUseBlock,
+  MeridianAgentConfig,
+} from "./agents.js";
+
+// Effect Layer — dependency injection
+export { MeridianService, MeridianLive } from "./layer.js";
+
 // Codec (for advanced use / testing)
 export {
   encode,

package/src/layer.ts

@@ -0,0 +1,44 @@
+import { Context, Effect, Layer } from "effect";
+import { MeridianClient, type MeridianClientConfig } from "./client.js";
+import type { TokenParseError, TokenExpiredError } from "./errors.js";
+
+/**
+ * Effect Context tag for `MeridianClient`.
+ *
+ * Use this to inject a `MeridianClient` into Effect programs via `MeridianLive`.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { MeridianService, MeridianLive } from 'meridian-sdk';
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* MeridianService;
+ *   client.gcounter('visitors').increment();
+ * });
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(MeridianLive(config))));
+ * ```
+ */
+export class MeridianService extends Context.Tag("MeridianService")<
+  MeridianService,
+  MeridianClient
+>() {}
+
+/**
+ * Scoped Layer that creates a `MeridianClient` and closes it on release.
+ *
+ * The client is created with `MeridianClient.create(config)` and closed
+ * automatically when the scope is closed (e.g. at the end of `Effect.runPromise`
+ * or when `Layer.build` is interrupted).
+ */
+export const MeridianLive = (
+  config: MeridianClientConfig,
+): Layer.Layer<MeridianService, TokenParseError | TokenExpiredError> =>
+  Layer.scoped(
+    MeridianService,
+    Effect.acquireRelease(
+      MeridianClient.create(config),
+      (client) => Effect.sync(() => client.close()),
+    ),
+  );

package/src/schema.ts

@@ -47,6 +47,7 @@ export const ClientMsg = Schema.Union(
       crdt_id: Schema.String,
       op_bytes: Schema.Uint8ArrayFromSelf,
       ttl_ms: Schema.optional(Schema.Number),
+      client_seq: Schema.optional(Schema.Number),
     }),
   }),
   Schema.Struct({
@@ -68,7 +69,7 @@ export const ServerMsg = Schema.Union(
       delta_bytes: Schema.Uint8ArrayFromSelf,
     }),
   }),
-  Schema.Struct({ Ack: Schema.Struct({ seq: Schema.Number }) }),
+  Schema.Struct({ Ack: Schema.Struct({ seq: Schema.Number, client_seq: Schema.optional(Schema.Number) }) }),
   Schema.Struct({
     Error: Schema.Struct({ code: Schema.Number, message: Schema.String }),
   }),

package/src/sync/delta.ts

@@ -72,12 +72,22 @@ export const decodePresenceDelta = (bytes: Uint8Array): PresenceDelta => {
   return { changes: raw.changes ?? {} };
 };
 
+export interface RGADelta {
+  text: string;
+}
+
+export const decodeRGADelta = (bytes: Uint8Array): RGADelta => {
+  const raw = decode(bytes) as { text?: string };
+  return { text: raw.text ?? "" };
+};
+
 export type CrdtValueDelta =
   | { GCounter: GCounterDelta }
   | { PNCounter: PNCounterDelta }
   | { ORSet: ORSetDelta }
   | { LwwRegister: LwwDelta }
-  | { Presence: PresenceDelta };
+  | { Presence: PresenceDelta }
+  | { RGA: RGADelta };
 
 export interface CRDTMapDelta {
   deltas: Record<string, CrdtValueDelta>;

package/src/transport/http.ts

@@ -16,8 +16,20 @@ export interface HttpClientConfig {
   timeoutMs?: number;
 }
 
+export interface HistoryEntry {
+  seq: number;
+  timestamp_ms: number;
+  op: unknown;
+}
+
+export interface HistoryResponse {
+  crdt_id: string;
+  entries: HistoryEntry[];
+  next_seq: number | null;
+}
+
 export class HttpClient {
-  private readonly baseUrl: string;
+  readonly baseUrl: string;
   private readonly timeoutMs: number;
   token: string;
 
@@ -48,6 +60,11 @@ export class HttpClient {
     return this.request(CrdtGetResponse, "GET", path);
   }
 
+  getHistory(ns: string, id: string, sinceSeq = 0, limit = 50): Promise<HistoryResponse> {
+    const url = `${this.baseUrl}/v1/namespaces/${ns}/crdts/${encodeURIComponent(id)}/history?since_seq=${sinceSeq}&limit=${limit}`;
+    return fetch(url, { headers: { Authorization: `Bearer ${this.token}` } }).then(r => r.json() as Promise<HistoryResponse>);
+  }
+
   issueToken(
     ns: string,
     opts: { client_id: number; ttl_ms: number; permissions: Permissions },

package/src/transport/websocket.ts

@@ -1,14 +1,23 @@
-import { Effect } from "effect";
+import {
+  Effect,
+  Fiber,
+  Layer,
+  ManagedRuntime,
+  Option,
+  Queue,
+  Schedule,
+  Duration,
+} from "effect";
 import { encodeClientMsg, decodeServerMsg, encodeVectorClock } from "../codec.js";
 import type { ServerMsg, VectorClock } from "../schema.js";
 import {
   BACKOFF_INITIAL_MS,
   BACKOFF_MAX_MS,
   BACKOFF_MULTIPLIER,
-  JITTER_MULTIPLIER,
   DEFAULT_TIMEOUT_MS,
   OFFLINE_QUEUE_MAX,
 } from "../constants.js";
+import { TransportError } from "../errors.js";
 
 export type WsState =
   | "DISCONNECTED"
@@ -24,46 +33,84 @@ export interface WsTransportConfig {
   maxBackoffMs?: number;
 }
 
+type ClientMsg = Parameters<typeof encodeClientMsg>[0];
+
 export class WsTransport {
   private readonly config: WsTransportConfig;
   private readonly maxBackoffMs: number;
 
   private ws: WebSocket | null = null;
   private state: WsState = "DISCONNECTED";
-  private backoffMs = BACKOFF_INITIAL_MS;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private closed = false;
 
+  // Effect runtime owned by this transport
+  private readonly runtime = ManagedRuntime.make(Layer.empty);
+  private lifecycleFiber: Fiber.RuntimeFiber<void, never> | null = null;
+
+  // State change listeners (replacing fragile function-chain pattern)
+  private readonly stateListeners = new Set<(state: WsState) => void>();
+
   private readonly subscriptions = new Map<string, VectorClock>();
-  private readonly pendingOps: Parameters<typeof encodeClientMsg>[0][] = [];
+
+  // Effect sliding queue — drops oldest when full (same behaviour as previous array)
+  private readonly pendingQueue: Queue.Queue<ClientMsg>;
+
+  // Latency tracking
+  private nextClientSeq = 0;
+  /** Maps client_seq → `performance.now()` timestamp at send time. */
+  private readonly pendingAcks = new Map<number, number>();
+  private readonly latencySamples: number[] = [];           // rolling window of round-trip ms
+  private static readonly LATENCY_WINDOW = 128;
 
   constructor(config: WsTransportConfig) {
     this.config = config;
     this.maxBackoffMs = config.maxBackoffMs ?? BACKOFF_MAX_MS;
+
+    // Queue creation is synchronous
+    this.pendingQueue = Effect.runSync(Queue.sliding<ClientMsg>(OFFLINE_QUEUE_MAX));
+
+    // Register initial onStateChange listener if provided
+    if (config.onStateChange) {
+      this.stateListeners.add(config.onStateChange);
+    }
   }
 
   connect(): void {
     if (this.closed) return;
     this.closed = false;
-    this.doConnect();
+    this.transitionTo("CONNECTING");
+    const ws = this.makeWs();
+    this.lifecycleFiber = this.runtime.runFork(this.buildLifecycleEffect(ws));
   }
 
   close(): void {
     this.closed = true;
-    this.pendingOps.length = 0;
-    this.clearReconnectTimer();
+    // Drain synchronously so pendingOpCount returns 0 immediately after close()
+    Effect.runSync(Queue.takeAll(this.pendingQueue));
+    this.runtime.runFork(Queue.shutdown(this.pendingQueue));
     this.transitionTo("CLOSING");
+    if (this.lifecycleFiber !== null) {
+      const fiber = this.lifecycleFiber;
+      this.lifecycleFiber = null;
+      this.runtime.runFork(Fiber.interrupt(fiber));
+    }
     this.ws?.close(1000, "client close");
+    this.ws = null;
+    void this.runtime.dispose();
   }
 
   reopen(): void {
-    // Disown the current ws before creating a new one so its close event
-    // fires with ws !== this.ws and does not trigger scheduleReconnect.
+    if (this.lifecycleFiber !== null) {
+      const fiber = this.lifecycleFiber;
+      this.lifecycleFiber = null;
+      this.runtime.runFork(Fiber.interrupt(fiber));
+    }
     const old = this.ws;
     this.ws = null;
     old?.close(1000, "reopen");
     this.closed = false;
-    this.doConnect();
+    this.transitionTo("CONNECTING");
+    this.lifecycleFiber = this.runtime.runFork(this.buildLifecycleEffect(this.makeWs()));
   }
 
   subscribe(crdtId: string, sinceVc: VectorClock = {}): void {
@@ -77,19 +124,49 @@ export class WsTransport {
     this.subscriptions.set(crdtId, vc);
   }
 
-  send(msg: Parameters<typeof encodeClientMsg>[0]): void {
+  send(msg: ClientMsg): void {
+    const tagged = this.tagOp(msg);
     if (this.state !== "CONNECTED" || this.ws === null) {
-      if (this.pendingOps.length >= OFFLINE_QUEUE_MAX) {
-        this.pendingOps.shift(); // drop oldest to make room
-      }
-      this.pendingOps.push(msg);
+      // sliding queue drops oldest automatically if full
+      this.runtime.runFork(Queue.offer(this.pendingQueue, tagged));
       return;
     }
-    this.ws.send(encodeClientMsg(msg));
+    this.ws.send(encodeClientMsg(tagged));
+  }
+
+  /** Returns P50 and P99 op round-trip latency in milliseconds, or null if not enough samples. */
+  getLatencyStats(): { p50: number; p99: number; count: number } | null {
+    if (this.latencySamples.length < 2) return null;
+    const sorted = [...this.latencySamples].sort((a, b) => a - b);
+    const p50 = sorted[Math.floor(sorted.length * 0.5)] ?? 0;
+    const p99 = sorted[Math.floor(sorted.length * 0.99)] ?? 0;
+    return { p50, p99, count: sorted.length };
+  }
+
+  private tagOp(msg: ClientMsg): ClientMsg {
+    if (!("Op" in msg)) return msg;
+    const seq = this.nextClientSeq++;
+    this.pendingAcks.set(seq, performance.now());
+    return { Op: { ...msg.Op, client_seq: seq } };
+  }
+
+  private recordAck(clientSeq: number): void {
+    const sentAt = this.pendingAcks.get(clientSeq);
+    if (sentAt === undefined) return;
+    this.pendingAcks.delete(clientSeq);
+    const rtt = performance.now() - sentAt;
+    this.latencySamples.push(rtt);
+    if (this.latencySamples.length > WsTransport.LATENCY_WINDOW) {
+      this.latencySamples.shift();
+    }
   }
 
   get pendingOpCount(): number {
-    return this.pendingOps.length;
+    try {
+      return Effect.runSync(Queue.size(this.pendingQueue));
+    } catch {
+      return 0;
+    }
   }
 
   /**
@@ -97,18 +174,8 @@ export class WsTransport {
    * Compatible with React's `useSyncExternalStore` subscribe parameter.
    */
   onStateChange(listener: (state: WsState) => void): () => void {
-    const prev = this.config.onStateChange;
-    this.config.onStateChange = (s) => {
-      prev?.(s);
-      listener(s);
-    };
-    return () => {
-      if (prev !== undefined) {
-        this.config.onStateChange = prev;
-      } else {
-        delete (this.config as Partial<WsTransportConfig>).onStateChange;
-      }
-    };
+    this.stateListeners.add(listener);
+    return () => { this.stateListeners.delete(listener); };
   }
 
   get currentState(): WsState {
@@ -118,90 +185,141 @@ export class WsTransport {
   waitForConnected(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<void> {
     if (this.state === "CONNECTED") return Promise.resolve();
     return new Promise((resolve, reject) => {
-      const orig = this.config.onStateChange;
-      const restore = () => {
-        if (orig !== undefined) {
-          this.config.onStateChange = orig;
-        } else {
-          delete (this.config as Partial<WsTransportConfig>).onStateChange;
-        }
-      };
       const timer = setTimeout(() => {
-        restore();
+        this.stateListeners.delete(listener);
         reject(new Error("WsTransport: connect timeout"));
       }, timeoutMs);
-      this.config.onStateChange = (s) => {
-        orig?.(s);
+      const listener = (s: WsState) => {
         if (s === "CONNECTED") {
           clearTimeout(timer);
-          restore();
+          this.stateListeners.delete(listener);
           resolve();
         }
       };
+      this.stateListeners.add(listener);
     });
   }
 
-  private doConnect(): void {
-    if (this.closed) return;
-    this.transitionTo("CONNECTING");
+  // ---------------------------------------------------------------------------
+  // Effect lifecycle
+  // ---------------------------------------------------------------------------
 
+  private makeWs(): {
+    ws: WebSocket;
+    connected: Promise<WebSocket>;
+    cancel: () => void;
+  } {
     const url = `${this.config.url}${this.config.url.includes("?") ? "&" : "?"}token=${encodeURIComponent(this.config.token)}`;
     const ws = new WebSocket(url);
     ws.binaryType = "arraybuffer";
-    this.ws = ws;
 
-    ws.addEventListener("open", () => {
-      if (ws !== this.ws) return;
-      this.backoffMs = BACKOFF_INITIAL_MS;
+    // Register open/error listeners synchronously so they fire even if the
+    // Fiber hasn't started yet (runFork is async).
+    let resolve!: (ws: WebSocket) => void;
+    let reject!: (e: TransportError) => void;
+    const connected = new Promise<WebSocket>((res, rej) => { resolve = res; reject = rej; });
+
+    const onOpen = () => {
+      this.ws = ws;
       this.transitionTo("CONNECTED");
       this.resubscribeAll();
-    });
+      resolve(ws);
+    };
+    const onError = () => {
+      reject(new TransportError({ message: "WebSocket connection failed" }));
+    };
+    ws.addEventListener("open", onOpen, { once: true });
+    ws.addEventListener("error", onError, { once: true });
 
-    ws.addEventListener("message", (event: MessageEvent) => {
-      if (ws !== this.ws) return;
-      const bytes = new Uint8Array(event.data as ArrayBuffer);
-      Effect.runPromise(decodeServerMsg(bytes)).then(
-        (msg) => { this.config.onMessage(msg); },
-        (e) => { console.warn("[meridian] failed to decode server message", e); },
-      );
-    });
+    const cancel = () => {
+      ws.removeEventListener("open", onOpen);
+      ws.removeEventListener("error", onError);
+      ws.close(1000, "fiber interrupt");
+    };
+    return { ws, connected, cancel };
+  }
 
-    ws.addEventListener("close", () => {
-      if (ws !== this.ws) return;
-      this.ws = null;
-      if (!this.closed) {
-        this.transitionTo("DISCONNECTED");
-        this.scheduleReconnect();
+  private buildLifecycleEffect(wsHandle: ReturnType<WsTransport["makeWs"]>): Effect.Effect<void, never> {
+    const { ws, connected, cancel } = wsHandle;
+
+    const connectOnce = Effect.async<WebSocket, TransportError>((resume) => {
+      if (this.closed) {
+        cancel();
+        resume(Effect.fail(new TransportError({ message: "transport closed" })));
+        return Effect.void;
       }
-    });
 
-    ws.addEventListener("error", () => {
-      // HACK: The "close" event fires right after an error — let that handler drive reconnect logic.
+      // connected already has the listeners; just await its outcome
+      connected.then(
+        (w) => resume(Effect.succeed(w)),
+        () => resume(Effect.fail(new TransportError({ message: "WebSocket connection failed" }))),
+      );
+
+      // Finalizer — called if Fiber is interrupted before open
+      return Effect.sync(cancel);
     });
-  }
 
-  private scheduleReconnect(): void {
-    if (this.closed) return;
-    const jitter = this.backoffMs * JITTER_MULTIPLIER * (Math.random() * 2 - 1);
-    const delay = Math.round(this.backoffMs + jitter);
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.doConnect();
-    }, delay);
-    this.backoffMs = Math.min(this.backoffMs * BACKOFF_MULTIPLIER, this.maxBackoffMs);
-  }
-
-  private clearReconnectTimer(): void {
-    if (this.reconnectTimer !== null) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
+    const handleConnection = (_ws: WebSocket): Effect.Effect<void, TransportError> =>
+      Effect.async((resume) => {
+        const onMessage = (event: MessageEvent) => {
+          const bytes = new Uint8Array(event.data as ArrayBuffer);
+          Effect.runPromise(decodeServerMsg(bytes)).then(
+            (msg) => {
+              if ("Ack" in msg && msg.Ack.client_seq !== undefined) {
+                this.recordAck(msg.Ack.client_seq);
+              }
+              this.config.onMessage(msg);
+            },
+            (e) => { console.warn("[meridian] failed to decode server message", e); },
+          );
+        };
+        const onClose = () => {
+          this.ws = null;
+          resume(Effect.fail(new TransportError({ message: "WebSocket closed" })));
+        };
+
+        ws.addEventListener("message", onMessage);
+        ws.addEventListener("close", onClose, { once: true });
+
+        // Finalizer — clean up listeners if Fiber is interrupted
+        return Effect.sync(() => {
+          ws.removeEventListener("message", onMessage);
+          ws.removeEventListener("close", onClose);
+          ws.close(1000, "fiber interrupt");
+        });
+      });
+
+    const reconnectSchedule = Schedule.exponential(
+      Duration.millis(BACKOFF_INITIAL_MS),
+      BACKOFF_MULTIPLIER,
+    ).pipe(
+      Schedule.map((d) => Duration.min(d, Duration.millis(this.maxBackoffMs))),
+      Schedule.jittered,
+    );
+
+    return connectOnce.pipe(
+      Effect.flatMap(handleConnection),
+      Effect.tapError(() => Effect.sync(() => {
+        if (!this.closed) this.transitionTo("DISCONNECTED");
+      })),
+      Effect.retry(reconnectSchedule),
+      Effect.catchAll(() => Effect.void),
+    );
   }
 
+  // ---------------------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------------------
+
   private transitionTo(next: WsState): void {
     if (this.state === next) return;
     this.state = next;
+    // Notify initial listener from config (for backward compat with client.ts)
     this.config.onStateChange?.(next);
+    // Notify all registered listeners
+    for (const listener of this.stateListeners) {
+      listener(next);
+    }
   }
 
   private resubscribeAll(): void {
@@ -212,18 +330,24 @@ export class WsTransport {
   }
 
   private flushPendingOps(): void {
-    const ops = this.pendingOps.splice(0);
-    for (let i = 0; i < ops.length; i++) {
-      const op = ops[i];
-      if (op === undefined) continue;
-      try {
-        this.ws?.send(encodeClientMsg(op));
-      } catch {
-        // WebSocket closed between open and flush — re-queue remaining ops.
-        this.pendingOps.unshift(...ops.slice(i));
-        break;
-      }
-    }
+    this.runtime.runFork(
+      Effect.gen((function* (this: WsTransport) {
+        for (;;) {
+          const next: Option.Option<ClientMsg> = yield* Queue.poll(this.pendingQueue);
+          if (Option.isNone(next)) break;
+          if (this.ws === null || this.state !== "CONNECTED") {
+            yield* Queue.offer(this.pendingQueue, next.value);
+            break;
+          }
+          try {
+            this.ws.send(encodeClientMsg(this.tagOp(next.value)));
+          } catch {
+            yield* Queue.offer(this.pendingQueue, next.value);
+            break;
+          }
+        }
+      }).bind(this)),
+    );
   }
 
   private sendSubscribe(crdtId: string, vc: VectorClock): void {