meridian-sdk 1.2.0 → 1.3.0

package/src/agents.ts

@@ -1,18 +1,41 @@
 /**
- * Meridian × Anthropic Claude tool use helpers.
+ * Meridian AI agent tool use helpers.
  *
- * Generates Anthropic-compatible `Tool` definitions from a list of CRDT IDs
+ * Generates provider-compatible tool definitions from a list of CRDT IDs
  * and executes tool calls against a Meridian server via HTTP (no WebSocket).
  *
- * Usage:
+ * Supported providers:
+ * - Anthropic Claude — `getMeridianTools()` (default)
+ * - OpenAI GPT       — `toOpenAITools(getMeridianTools(...))`
+ * - Google Gemini    — `toGeminiTools(getMeridianTools(...))`
+ *
+ * Usage (Anthropic):
  * ```ts
  * import { getMeridianTools, executeMeridianTool } from "meridian-sdk";
  *
- * const tools = getMeridianTools({ baseUrl, token, namespace, crdtIds: ["counter", "tasks"] });
+ * const tools = getMeridianTools(config, ["counter", "tasks"]);
+ * // Pass to Anthropic messages.create({ tools })
+ * const result = await executeMeridianTool(config, toolUseBlock);
+ * ```
+ *
+ * Usage (OpenAI):
+ * ```ts
+ * import { getMeridianTools, toOpenAITools, executeOpenAITool } from "meridian-sdk";
+ *
+ * const tools = toOpenAITools(getMeridianTools(config, ["counter", "tasks"]));
+ * // Pass to openai.chat.completions.create({ tools })
+ * // For each tool_call in the response — pass directly, no wrapping:
+ * const result = await executeOpenAITool(config, call);
+ * ```
+ *
+ * Usage (Gemini):
+ * ```ts
+ * import { getMeridianTools, toGeminiTools, executeGeminiTool } from "meridian-sdk";
  *
- * // Pass tools to Anthropic messages.create(...)
- * // Then for each tool_use block in the response:
- * const result = await executeMeridianTool({ baseUrl, token, namespace }, toolUseBlock);
+ * const tools = toGeminiTools(getMeridianTools(config, ["counter", "tasks"]));
+ * // Pass to model.generateContent({ tools })
+ * // For each functionCall part — pass directly, no wrapping:
+ * const result = await executeGeminiTool(config, part.functionCall);
  * ```
  */
 
@@ -28,6 +51,94 @@ export interface Tool {
   };
 }
 
+// ---------------------------------------------------------------------------
+// OpenAI adapter
+// ---------------------------------------------------------------------------
+
+/** OpenAI-compatible tool definition (Chat Completions `tools` array entry). */
+export interface OpenAITool {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: {
+      type: "object";
+      properties: Record<string, { type: string; description: string }>;
+      required?: string[];
+    };
+  };
+}
+
+/**
+ * Convert Meridian tools to OpenAI Chat Completions format.
+ *
+ * ```ts
+ * const tools = toOpenAITools(getMeridianTools(config, crdtIds));
+ * // openai.chat.completions.create({ tools })
+ * ```
+ */
+export function toOpenAITools(tools: Tool[]): OpenAITool[] {
+  return tools.map(t => ({
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: {
+        type: "object",
+        properties: t.input_schema.properties,
+        ...(t.input_schema.required ? { required: t.input_schema.required } : {}),
+      },
+    },
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Gemini adapter
+// ---------------------------------------------------------------------------
+
+/** Gemini FunctionDeclaration (single entry inside a `Tool.functionDeclarations` array). */
+export interface GeminiFunctionDeclaration {
+  name: string;
+  description: string;
+  parameters: {
+    type: "OBJECT";
+    properties: Record<string, { type: string; description: string }>;
+    required?: string[];
+  };
+}
+
+/** Gemini `Tool` wrapper passed to `model.generateContent({ tools })`. */
+export interface GeminiTool {
+  functionDeclarations: GeminiFunctionDeclaration[];
+}
+
+/**
+ * Convert Meridian tools to Google Gemini format.
+ *
+ * ```ts
+ * const tools = toGeminiTools(getMeridianTools(config, crdtIds));
+ * // model.generateContent({ tools })
+ * ```
+ */
+export function toGeminiTools(tools: Tool[]): GeminiTool {
+  return {
+    functionDeclarations: tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: {
+        type: "OBJECT",
+        properties: t.input_schema.properties,
+        ...(t.input_schema.required ? { required: t.input_schema.required } : {}),
+      },
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider-specific input types (structural matches — no provider SDK deps)
+// ---------------------------------------------------------------------------
+
+/** Anthropic tool_use block — matches `ContentBlock` from `@anthropic-ai/sdk`. */
 export interface ToolUseBlock {
   type: "tool_use";
   id: string;
@@ -35,6 +146,29 @@ export interface ToolUseBlock {
   input: Record<string, unknown>;
 }
 
+/**
+ * OpenAI tool call — structurally matches `ChatCompletionMessageToolCall`
+ * from the `openai` package. Pass directly from `response.choices[0].message.tool_calls`.
+ */
+export interface OpenAIToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    /** JSON-encoded arguments string, as returned by the OpenAI API. */
+    arguments: string;
+  };
+}
+
+/**
+ * Gemini function call — structurally matches `FunctionCall` from
+ * `@google/generative-ai`. Pass directly from `part.functionCall`.
+ */
+export interface GeminiFunctionCall {
+  name: string;
+  args: Record<string, unknown>;
+}
+
 export interface MeridianAgentConfig {
   /** HTTP base URL of the Meridian server (e.g. https://meridian.example.com) */
   baseUrl: string;
@@ -114,19 +248,21 @@ export function getMeridianTools(
   return tools;
 }
 
+// ---------------------------------------------------------------------------
+// Shared dispatcher (private)
+// ---------------------------------------------------------------------------
+
 /**
- * Execute a Meridian tool call returned by Claude.
- *
- * Returns a JSON string suitable for the `content` field of a `tool_result` block.
+ * Core dispatch logic — routes a (name, input) pair to the right HTTP operation.
+ * All provider-specific executors delegate here.
  */
-export async function executeMeridianTool(
+async function dispatchTool(
   config: MeridianAgentConfig,
-  toolUse: ToolUseBlock,
+  name: string,
+  input: Record<string, unknown>,
 ): Promise<string> {
   const { baseUrl, token, namespace } = config;
-  const { name, input } = toolUse;
 
-  // Detect operation type and crdt_id from tool name
   const readMatch = name.match(/^meridian_read_(.+)$/);
   const incrementMatch = name.match(/^meridian_increment_(.+)$/);
   const setMatch = name.match(/^meridian_set_(.+)$/);
@@ -156,7 +292,7 @@ export async function executeMeridianTool(
   if (addMatch?.[1]) {
     const crdtId = addMatch[1].replace(/_/g, "-");
     // Always store as a string so useORSet<string> can read it back directly.
-    // If Claude passes a JSON object, re-serialize it to a stable string.
+    // If the model passes a JSON object, re-serialize it to a stable string.
     const rawEl = input.element;
     const element: string = typeof rawEl === "string" ? rawEl : JSON.stringify(rawEl ?? null);
     const clientId = Number(input.client_id ?? 1);
@@ -166,6 +302,79 @@ export async function executeMeridianTool(
   return JSON.stringify({ error: `Unknown tool: ${name}` });
 }
 
+// ---------------------------------------------------------------------------
+// Provider executors
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a Meridian tool call returned by **Anthropic Claude**.
+ *
+ * Returns a JSON string suitable for the `content` field of a `tool_result` block.
+ *
+ * ```ts
+ * for (const block of response.content) {
+ *   if (block.type === "tool_use") {
+ *     const result = await executeMeridianTool(config, block);
+ *     toolResults.push({ type: "tool_result", tool_use_id: block.id, content: result });
+ *   }
+ * }
+ * ```
+ */
+export async function executeMeridianTool(
+  config: MeridianAgentConfig,
+  toolUse: ToolUseBlock,
+): Promise<string> {
+  return dispatchTool(config, toolUse.name, toolUse.input);
+}
+
+/**
+ * Execute a Meridian tool call returned by **OpenAI**.
+ *
+ * Pass `tool_call` directly from `response.choices[0].message.tool_calls` —
+ * no wrapping required. Returns a JSON string for the `tool` role message content.
+ *
+ * ```ts
+ * for (const call of response.choices[0].message.tool_calls ?? []) {
+ *   const result = await executeOpenAITool(config, call);
+ *   messages.push({ role: "tool", tool_call_id: call.id, content: result });
+ * }
+ * ```
+ */
+export async function executeOpenAITool(
+  config: MeridianAgentConfig,
+  toolCall: OpenAIToolCall,
+): Promise<string> {
+  let input: Record<string, unknown>;
+  try {
+    input = JSON.parse(toolCall.function.arguments) as Record<string, unknown>;
+  } catch {
+    return JSON.stringify({ error: "Failed to parse tool call arguments" });
+  }
+  return dispatchTool(config, toolCall.function.name, input);
+}
+
+/**
+ * Execute a Meridian tool call returned by **Google Gemini**.
+ *
+ * Pass `part.functionCall` directly — no wrapping, no id hack required.
+ * Returns a JSON string for the `functionResponse` part content.
+ *
+ * ```ts
+ * for (const part of response.candidates?.[0].content.parts ?? []) {
+ *   if (part.functionCall) {
+ *     const result = await executeGeminiTool(config, part.functionCall);
+ *     // pass result back as functionResponse part
+ *   }
+ * }
+ * ```
+ */
+export async function executeGeminiTool(
+  config: MeridianAgentConfig,
+  functionCall: GeminiFunctionCall,
+): Promise<string> {
+  return dispatchTool(config, functionCall.name, functionCall.args);
+}
+
 async function readCrdt(
   baseUrl: string,
   token: string,

package/src/client.ts

@@ -11,6 +11,8 @@ import { PresenceHandle } from "./crdt/presence.js";
 import { CRDTMapHandle } from "./crdt/crdtmap.js";
 import { AwarenessHandle } from "./crdt/awareness.js";
 import { RGAHandle } from "./crdt/rga.js";
+import { TreeHandle } from "./crdt/tree.js";
+import type { CrdtValidator } from "./validation/index.js";
 import {
   decodeGCounterDelta,
   decodePNCounterDelta,
@@ -19,7 +21,9 @@ import {
   decodePresenceDelta,
   decodeCRDTMapDelta,
   decodeRGADelta,
+  decodeTreeDelta,
 } from "./sync/delta.js";
+import type { TreeNodeValue } from "./sync/delta.js";
 import { parseAndValidateToken } from "./auth/token.js";
 import type { ServerMsg, TokenClaims } from "./schema.js";
 import type { TokenParseError, TokenExpiredError } from "./errors.js";
@@ -63,6 +67,11 @@ export interface RGASnapshotEntry {
   crdtId: string;
   text: string;
 }
+export interface TreeSnapshotEntry {
+  type: "tree";
+  crdtId: string;
+  roots: TreeNodeValue[];
+}
 export type CRDTSnapshotEntry =
   | GCounterSnapshotEntry
   | PNCounterSnapshotEntry
@@ -70,7 +79,8 @@ export type CRDTSnapshotEntry =
   | LwwRegisterSnapshotEntry
   | PresenceSnapshotEntry
   | CRDTMapSnapshotEntry
-  | RGASnapshotEntry;
+  | RGASnapshotEntry
+  | TreeSnapshotEntry;
 
 export interface DeltaEvent {
   crdtId: string;
@@ -136,6 +146,7 @@ export class MeridianClient {
   private readonly cmHandles = new Map<string, CRDTMapHandle>();
   private readonly awHandles = new Map<string, AwarenessHandle<unknown>>();
   private readonly rgaHandles = new Map<string, RGAHandle>();
+  private readonly treeHandles = new Map<string, TreeHandle>();
 
   private readonly anyListeners = new Set<() => void>();
   private readonly deltaListeners = new Set<(event: DeltaEvent) => void>();
@@ -382,10 +393,10 @@ export class MeridianClient {
    * doc.onChange(text => console.log(text));
    * ```
    */
-  rga(crdtId: string): RGAHandle {
+  rga(crdtId: string, opts?: { validator?: CrdtValidator }): RGAHandle {
     let handle = this.rgaHandles.get(crdtId);
     if (!handle) {
-      handle = new RGAHandle({ crdtId, clientId: this.clientId, transport: this.transport });
+      handle = new RGAHandle({ crdtId, clientId: this.clientId, transport: this.transport, ...(opts?.validator !== undefined && { validator: opts.validator }) });
       this.rgaHandles.set(crdtId, handle);
       this.transport.subscribe(crdtId);
       this.handleUnsubs.push(handle.onChange(() => { this.notifyAnyChange(); }));
@@ -393,6 +404,36 @@ export class MeridianClient {
     return handle;
   }
 
+  /**
+   * Returns a handle for a TreeCRDT — a convergent hierarchical tree.
+   *
+   * Use this for outlines, document trees, mind maps, or any nested structure
+   * that needs concurrent editing. Concurrent moves use Kleppmann (2021)
+   * move semantics: cycle-creating moves are discarded, all replicas converge.
+   *
+   * Handles are cached by `crdtId`; the same handle is returned for repeated calls.
+   *
+   * @param crdtId - Logical CRDT identifier (e.g. `"tree:outline"`).
+   *
+   * @example
+   * ```ts
+   * const tree = client.tree('doc:outline');
+   * const rootId = tree.addNode(null, 'a0', 'Introduction');
+   * const childId = tree.addNode(rootId, 'a0', 'Chapter 1');
+   * tree.onChange(t => console.log(t.roots));
+   * ```
+   */
+  tree(crdtId: string, opts?: { validator?: CrdtValidator }): TreeHandle {
+    let handle = this.treeHandles.get(crdtId);
+    if (!handle) {
+      handle = new TreeHandle({ crdtId, clientId: this.clientId, transport: this.transport, ...(opts?.validator !== undefined && { validator: opts.validator }) });
+      this.treeHandles.set(crdtId, handle);
+      this.transport.subscribe(crdtId);
+      this.handleUnsubs.push(handle.onChange(() => { this.notifyAnyChange(); }));
+    }
+    return handle;
+  }
+
   /**
    * Returns a handle for an ephemeral awareness channel.
    *
@@ -487,6 +528,8 @@ export class MeridianClient {
       crdts.push({ type: "crdtmap", crdtId, value: h.value() });
     for (const [crdtId, h] of this.rgaHandles)
       crdts.push({ type: "rga", crdtId, text: h.value() });
+    for (const [crdtId, h] of this.treeHandles)
+      crdts.push({ type: "tree", crdtId, roots: h.value().roots });
     return {
       namespace: this.namespace,
       clientId: this.clientId,
@@ -570,6 +613,12 @@ export class MeridianClient {
     if (rgaHandle) {
       try { rgaHandle.applyDelta(decodeRGADelta(delta_bytes)); } catch { /* stale */ }
       this.notifyDelta(crdt_id, "rga");
+      return;
+    }
+    const treeHandle = this.treeHandles.get(crdt_id);
+    if (treeHandle) {
+      try { treeHandle.applyDelta(decodeTreeDelta(delta_bytes)); } catch { /* stale */ }
+      this.notifyDelta(crdt_id, "tree");
     }
   }
 

package/src/conflict/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Conflict events emitted by TreeHandle when the server delta reveals a
+ * resolution that differs from what the local client expected.
+ *
+ * These are purely informational — the CRDT has already converged. Use them
+ * for audit logs, "track changes" UIs, or debugging concurrent edit scenarios.
+ */
+
+/**
+ * A concurrent MoveNode op caused a cycle (e.g. moving a node under its own
+ * descendant). The server silently discarded the move; the node stayed in
+ * place. This event tells you which move was dropped and where it tried to go.
+ */
+export interface MoveDiscardedEvent {
+  readonly kind: "move_discarded";
+  /** The node that was supposed to move. */
+  readonly nodeId: string;
+  /** Where the move tried to put it (null = root level). */
+  readonly attemptedParentId: string | null;
+  readonly attemptedPosition: string;
+  /** Where the node actually stayed. */
+  readonly actualParentId: string | null;
+  readonly actualPosition: string;
+  readonly at: number; // wall clock ms
+}
+
+/**
+ * Two concurrent MoveNode ops targeted the same node. The server picked a
+ * winner (highest HLC op_id); the loser's destination was overridden.
+ */
+export interface MoveReorderedEvent {
+  readonly kind: "move_reordered";
+  readonly nodeId: string;
+  /** Where the local client moved it (optimistic). */
+  readonly localParentId: string | null;
+  readonly localPosition: string;
+  /** Where the server placed it after conflict resolution. */
+  readonly serverParentId: string | null;
+  readonly serverPosition: string;
+  readonly at: number;
+}
+
+/**
+ * Two concurrent UpdateNode ops targeted the same node. LWW resolved it;
+ * the value with the older `updated_at` HLC was discarded.
+ */
+export interface LwwOverwriteEvent {
+  readonly kind: "lww_overwrite";
+  readonly nodeId: string;
+  /** The value that was overwritten (loser). */
+  readonly discardedValue: string;
+  /** The value that won. */
+  readonly winnerValue: string;
+  readonly at: number;
+}
+
+export type ConflictEvent =
+  | MoveDiscardedEvent
+  | MoveReorderedEvent
+  | LwwOverwriteEvent;

package/src/crdt/rga.ts

@@ -2,6 +2,7 @@ import { Chunk, Effect, Stream } from "effect";
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { RGADelta } from "../sync/delta.js";
+import { type CrdtValidator, runValidator } from "../validation/index.js";
 
 /**
  * Low-level handle for an RGA (Replicated Growable Array) CRDT — collaborative text editing.
@@ -16,18 +17,24 @@ export class RGAHandle {
   private readonly crdtId: string;
   private readonly clientId: number;
   private readonly transport: WsTransport;
+  private readonly validator: CrdtValidator | undefined;
   private readonly listeners = new Set<(value: string) => void>();
 
   constructor(opts: {
     crdtId: string;
     clientId: number;
     transport: WsTransport;
+    validator?: CrdtValidator;
   }) {
     this.crdtId = opts.crdtId;
     this.clientId = opts.clientId;
     this.transport = opts.transport;
+    this.validator = opts.validator;
   }
 
+  /** The CRDT key this handle is bound to. */
+  get id(): string { return this.crdtId; }
+
   /** Returns the current text content. */
   value(): string {
     return this.text;
@@ -53,14 +60,17 @@ export class RGAHandle {
 
   /**
    * Inserts `text` at visible position `pos` (0 = before all characters).
-   * Characters are inserted one by one in order using the RGA Insert op.
+   * Characters are inserted one by one using RGA Insert ops.
    *
-   * @param pos  - Visible character position (0-indexed).
-   * @param text - String to insert.
+   * @param pos   - Visible character position (0-indexed).
+   * @param text  - String to insert.
    * @param ttlMs - Optional TTL for the op.
+   * @returns The HLC strings ("wall_ms:logical:node_id") of the inserted nodes,
+   *          in insertion order. Used by UndoManager to record undo entries.
    */
-  insert(pos: number, text: string, ttlMs?: number): void {
-    if (text.length === 0) return;
+  insert(pos: number, text: string, ttlMs?: number): string[] {
+    if (text.length === 0) return [];
+    runValidator(this.validator, text);
 
     // Optimistic local update.
     this.text = this.text.slice(0, pos) + text + this.text.slice(pos);
@@ -69,12 +79,15 @@ export class RGAHandle {
     // Send each character as a separate RGA Insert op. The server reorders
     // them using their HLC IDs — sending individually preserves per-char identity.
     const wallMs = Date.now();
+    const nodeIds: string[] = [];
     for (let i = 0; i < text.length; i++) {
+      const id = { wall_ms: wallMs, logical: i, node_id: this.clientId };
+      nodeIds.push(`${wallMs}:${i}:${this.clientId}`);
       const op = encode({
         RGA: {
           Insert: {
-            id: { wall_ms: wallMs, logical: i, node_id: this.clientId },
-            origin_id: pos + i === 0 ? null : null, // server resolves via WAL
+            id,
+            origin_id: null, // server resolves via WAL
             content: text[i],
           },
         },
@@ -87,6 +100,32 @@ export class RGAHandle {
         },
       });
     }
+    return nodeIds;
+  }
+
+  /**
+   * Deletes the RGA node with the given HLC string ID directly.
+   * Used by UndoManager to undo an insert by its exact node identity,
+   * regardless of the current visible position.
+   *
+   * @param hlcString - HLC string "wall_ms:logical:node_id" returned by insert().
+   * @param ttlMs     - Optional TTL.
+   */
+  deleteById(hlcString: string, ttlMs?: number): void {
+    const parts = hlcString.split(":");
+    const id = {
+      wall_ms: Number(parts[0]),
+      logical: Number(parts[1]),
+      node_id: Number(parts[2]),
+    };
+    const op = encode({ RGA: { Delete: { id } } });
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: op,
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
+      },
+    });
   }
 
   /**