pingerchips-js 2.1.1 → 3.0.0

package/chat.js

@@ -0,0 +1,585 @@
+import { Pingerchips } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// PingerchipsChat — entry point for the chat Session API
+// ---------------------------------------------------------------------------
+
+/**
+ * Usage (client):
+ *   const chat = new PingerchipsChat(appKey, { authEndpoint: "/auth/chat" });
+ *   const session = await chat.connect(threadId, { clientId: "user-123" });
+ *   const run = await session.view.send("Hello");
+ *   run.toJSON(); // → { threadId, runId } — POST this to your agent endpoint
+ *
+ * Usage (agent — prefer AgentSession from pingerchips-js-server):
+ *   const chat = new PingerchipsChat(appKey);
+ *   const session = await chat.connectAgent(threadId, { secret, agentId });
+ */
+export class PingerchipsChat {
+  constructor(appKey, options = {}) {
+    if (!appKey) throw new Error("appKey required");
+    this.appKey = appKey;
+    this._options = options;
+    this._realtime =
+      options.realtime ||
+      new Pingerchips(appKey, {
+        endpoint: options.endpoint,
+        params: options.params,
+        serializer: options.serializer,
+        messageFormat: options.messageFormat,
+        reconnectAfterMs: options.reconnectAfterMs,
+        rejoinAfterMs: options.rejoinAfterMs,
+      });
+    if (options.autoConnect === false) this._realtime.disconnect();
+    this._sessions = {};
+  }
+
+  /**
+   * Connect as a human client. Fetches signed auth token from authEndpoint.
+   * @param {string} threadId
+   * @param {{ clientId: string, afterLogId?: number }} options
+   * @returns {Promise<ChatSession>}
+   */
+  async connect(threadId, { clientId, afterLogId } = {}) {
+    if (!clientId) throw new Error("clientId required");
+
+    const socketId = this._realtime.getSocketIdAsync
+      ? await this._realtime.getSocketIdAsync()
+      : this._realtime.socketId;
+    if (!socketId) throw new Error("Socket ID not available");
+
+    const joinParams = { client_id: clientId };
+    if (afterLogId != null) joinParams.after_log_id = afterLogId;
+
+    if (this._options.authEndpoint || this._options.authCallback) {
+      joinParams.auth = await this._resolveAuthToken(threadId, clientId, socketId);
+    }
+
+    return this._joinSession(threadId, joinParams);
+  }
+
+  /**
+   * Connect as an agent. Server-side only — never call from browser.
+   * @param {string} threadId
+   * @param {{ secret: string, agentId: string, afterLogId?: number }} options
+   * @returns {Promise<ChatSession>}
+   */
+  async connectAgent(threadId, { secret, agentId, afterLogId } = {}) {
+    if (!secret) throw new Error("secret required");
+    if (!agentId) throw new Error("agentId required");
+
+    const joinParams = { secret, agent_id: agentId };
+    if (afterLogId != null) joinParams.after_log_id = afterLogId;
+
+    return this._joinSession(threadId, joinParams);
+  }
+
+  async _resolveAuthToken(threadId, clientId, socketId) {
+    const params = {
+      socket_id: socketId,
+      thread_id: threadId,
+      client_id: clientId,
+    };
+
+    if (this._options.authCallback) {
+      const result = await invokeAuthCallback(this._options.authCallback, params);
+      return authToken(result);
+    }
+
+    const doFetch = this._options.fetch ?? globalThis.fetch;
+    const response = await doFetch(this._options.authEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this._options.authHeaders,
+      },
+      body: JSON.stringify({
+        ...(this._options.authParams ?? {}),
+        ...params,
+      }),
+    });
+
+    if (!response.ok) {
+      const err = await response.json().catch(() => ({ error: "Auth failed" }));
+      throw new Error(err.error || "Auth failed");
+    }
+
+    return authToken(await response.json());
+  }
+
+  _joinSession(threadId, joinParams) {
+    const topic = `chat:v1:app:${this.appKey}:thread:${threadId}`;
+    const channel = this._realtime.socket.channel(topic, joinParams);
+
+    return new Promise((resolve, reject) => {
+      channel
+        .join()
+        .receive("ok", () => {
+          this._sessions[threadId]?.close();
+          const session = new ChatSession(channel, threadId, this.appKey, () => {
+            if (this._sessions[threadId] === session) delete this._sessions[threadId];
+          });
+          this._sessions[threadId] = session;
+          resolve(session);
+        })
+        .receive("error", (resp) =>
+          reject(
+            new Error(
+              `Failed to join chat thread ${threadId}: ${JSON.stringify(resp)}`,
+            ),
+          ),
+        );
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ChatSession
+// ---------------------------------------------------------------------------
+
+export class ChatSession {
+  constructor(channel, threadId, appKey, onClose) {
+    this.threadId = threadId;
+    this.appKey = appKey;
+    this.view = new View(channel, threadId);
+    this._channel = channel;
+    this._onClose = onClose;
+    this._closed = false;
+  }
+
+  cancel(runId) {
+    return this.push("cancel", { runId });
+  }
+
+  push(event, payload) {
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push(event, payload)
+        .receive("ok", resolve)
+        .receive("error", (e) =>
+          reject(new Error(e.reason || `${event} failed`)),
+        );
+    });
+  }
+
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this.view.close();
+    this._channel.leave();
+    this._onClose?.();
+  }
+
+  on(event, callback) {
+    this.view.on(event, callback);
+    return this;
+  }
+
+  off(event, callback) {
+    this.view.off(event, callback);
+    return this;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// View
+// ---------------------------------------------------------------------------
+
+export class View {
+  constructor(channel, threadId) {
+    this._channel = channel;
+    this._threadId = threadId;
+    this._messages = [];
+    this._runs = {};
+    this._streams = {};
+    this._hasOlder = false;
+    this._logId = 0;
+    this._handlers = {};
+    this._siblingIndex = {};
+
+    this._channelRefs = [
+      ["snapshot", channel.on("snapshot", (p) => this._onSnapshot(p))],
+      ["change", channel.on("change", (p) => this._onChange(p))],
+      ["batch", channel.on("batch", (p) => this._onBatch(p))],
+      ["run:start", channel.on("run:start", (p) => this._onRunStart(p))],
+      ["run:end", channel.on("run:end", (p) => this._onRunEnd(p))],
+      ["run:suspend", channel.on("run:suspend", (p) => this._onRunSuspend(p))],
+      ["run:resume", channel.on("run:resume", (p) => this._onRunResume(p))],
+      ["tree:delta", channel.on("tree:delta", (p) => this._onTreeDelta(p))],
+    ];
+  }
+
+  // ── Read ──────────────────────────────────────────────────────────────────
+
+  getMessages() {
+    return this._buildBranch();
+  }
+  getChannelMessages() {
+    return [...this._messages];
+  }
+  get logId() {
+    return this._logId;
+  }
+  runs() {
+    return Object.values(this._runs);
+  }
+  hasOlder() {
+    return this._hasOlder;
+  }
+  getStream(runId) {
+    return this._streams[runId] ?? "";
+  }
+
+  // ── Write ─────────────────────────────────────────────────────────────────
+
+  send(text, { parentId, messageId = crypto.randomUUID(), runId = crypto.randomUUID(), role = "user" } = {}) {
+    const payload = { messageId, runId, text, role };
+    if (parentId != null) payload.parentId = parentId;
+
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("send", payload)
+        .receive("ok", (ack) =>
+          resolve(
+            new ActiveRun(runId, this._threadId, this._channel, {
+              messageId,
+              serial: ack?.serial,
+              status: ack?.status,
+            }),
+          ),
+        )
+        .receive("error", (e) => reject(new Error(e.reason || "send failed")));
+    });
+  }
+
+  regenerate(messageId, { runId = crypto.randomUUID(), parentId } = {}) {
+    const payload = { messageId, runId };
+    if (parentId != null) payload.parentId = parentId;
+
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("regenerate", payload)
+        .receive("ok", (ack) =>
+          resolve(
+            new ActiveRun(runId, this._threadId, this._channel, {
+              regeneratesMessageId: messageId,
+              serial: ack?.serial,
+            }),
+          ),
+        )
+        .receive("error", (e) =>
+          reject(new Error(e.reason || "regenerate failed")),
+        );
+    });
+  }
+
+  edit(messageId, content, { newMessageId = crypto.randomUUID(), runId = crypto.randomUUID() } = {}) {
+
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("edit", { messageId, text: content, newMessageId, runId })
+        .receive("ok", (ack) =>
+          resolve(
+            new ActiveRun(runId, this._threadId, this._channel, {
+              messageId: newMessageId,
+              forkOf: messageId,
+              serial: ack?.serial,
+              status: ack?.status,
+            }),
+          ),
+        )
+        .receive("error", (e) => reject(new Error(e.reason || "edit failed")));
+    });
+  }
+
+  loadOlder(limit = 50) {
+    const oldest = this._messages[0];
+    if (!oldest || !this._hasOlder) return Promise.resolve([]);
+
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("load_older", { beforeMessageId: oldest.messageId, limit })
+        .receive("ok", ({ messages, has_older }) => {
+          this._messages = [...messages, ...this._messages];
+          this._hasOlder = has_older;
+          this._emit("update");
+          resolve(messages);
+        })
+        .receive("error", (e) =>
+          reject(new Error(e.reason || "load_older failed")),
+        );
+    });
+  }
+
+  selectSibling(parentId, messageId) {
+    this._siblingIndex[parentId] = messageId;
+    this._emit("update");
+  }
+
+  approveTool(runId, toolCallId) {
+    return this._pushToolApproval(runId, toolCallId, true);
+  }
+
+  rejectTool(runId, toolCallId) {
+    return this._pushToolApproval(runId, toolCallId, false);
+  }
+
+  _pushToolApproval(runId, toolCallId, approved) {
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("tool_approval", { runId, toolCallId, approved })
+        .receive("ok", resolve)
+        .receive("error", (e) =>
+          reject(new Error(e.reason || "tool_approval failed")),
+        );
+    });
+  }
+
+  on(event, callback) {
+    (this._handlers[event] ??= []).push(callback);
+    return this;
+  }
+
+  off(event, callback) {
+    if (!callback) {
+      delete this._handlers[event];
+    } else {
+      this._handlers[event] = (this._handlers[event] || []).filter(
+        (h) => h !== callback,
+      );
+    }
+    return this;
+  }
+
+  // ── Server event handlers ─────────────────────────────────────────────────
+
+  _onSnapshot({ state, log_id, has_older }) {
+    this._messages = state.messages ?? [];
+    this._runs = state.runs ?? {};
+    this._hasOlder = has_older ?? false;
+    this._logId = log_id ?? 0;
+    this._streams = {};
+
+    for (const [key, value] of Object.entries(state)) {
+      if (key.startsWith("stream:")) this._streams[key.slice(7)] = value;
+    }
+
+    this._emit("update");
+  }
+
+  _onChange({ key, value, log_id }) {
+    if (log_id != null) this._logId = log_id;
+
+    if (key === "messages") {
+      this._messages = value ?? [];
+      this._emit("update");
+    } else if (key.startsWith("stream:")) {
+      const runId = key.slice(7);
+      if (value === null) delete this._streams[runId];
+      else this._streams[runId] = value;
+      this._emit("update");
+    } else if (key.startsWith("run:")) {
+      const runId = key.slice(4);
+      if (value === null) delete this._runs[runId];
+      else this._runs[runId] = value;
+      this._emit("run", this._runs[runId] ?? { runId, status: null });
+    }
+  }
+
+  _onBatch({ changes, log_id }) {
+    if (log_id != null) this._logId = log_id;
+
+    const changedRuns = [];
+    for (const { key, value } of changes) {
+      if (key === "messages") {
+        this._messages = value ?? [];
+      } else if (key.startsWith("stream:")) {
+        const runId = key.slice(7);
+        if (value === null) delete this._streams[runId];
+        else this._streams[runId] = value;
+      } else if (key.startsWith("run:")) {
+        const runId = key.slice(4);
+        if (value === null) delete this._runs[runId];
+        else this._runs[runId] = value;
+        changedRuns.push(this._runs[runId] ?? { runId, status: null });
+      }
+    }
+
+    for (const run of changedRuns) this._emit("run", run);
+    this._emit("update");
+  }
+
+  _onRunStart({ runId, ownerClientId, startedAt }) {
+    this._runs[runId] = {
+      runId,
+      ownerClientId,
+      status: "active",
+      startedAt,
+      endedAt: null,
+      suspendedTool: null,
+    };
+    this._emit("run", this._runs[runId]);
+    this._emit("run:start", this._runs[runId]);
+  }
+
+  _onRunEnd({ runId, reason, endedAt }) {
+    if (this._runs[runId])
+      this._runs[runId] = { ...this._runs[runId], status: reason, endedAt };
+    delete this._streams[runId];
+    this._emit("run", this._runs[runId] ?? { runId, status: reason });
+    this._emit("run:end", { runId, reason, endedAt });
+  }
+
+  _onRunSuspend({ runId, toolCallId, toolName, args }) {
+    if (this._runs[runId]) {
+      this._runs[runId] = {
+        ...this._runs[runId],
+        status: "suspended",
+        suspendedTool: { toolCallId, toolName, args },
+      };
+    }
+    this._emit("run", this._runs[runId]);
+    this._emit("run:suspended", { runId, toolCallId, toolName, args });
+    this._emit("run:suspend", { runId, toolCallId, toolName, args });
+  }
+
+  _onRunResume({ runId }) {
+    if (this._runs[runId]) {
+      this._runs[runId] = {
+        ...this._runs[runId],
+        status: "active",
+        suspendedTool: null,
+      };
+    }
+    this._emit("run", this._runs[runId]);
+    this._emit("run:resume", { runId });
+  }
+
+  _onTreeDelta({ node }) {
+    if (!node || !node.id) return;
+    const idx = this._messages.findIndex((m) => m.messageId === node.id);
+    // Normalise the server node shape back to the wire message shape the
+    // branch resolver expects.
+    const msg = {
+      messageId: node.id,
+      parentId: node.parent_id ?? null,
+      forkOf: node.fork_of ?? null,
+      msgRegenerate: node.msg_regenerate ?? null,
+      runId: node.run_id ?? null,
+      ownerClientId: node.owner_client_id ?? null,
+      role: node.role,
+      status: node.status,
+      content: node.content,
+      createdAt: node.created_at,
+    };
+    if (idx === -1) this._messages = [...this._messages, msg];
+    else this._messages = this._messages.map((m, i) => (i === idx ? msg : m));
+    this._emit("update");
+  }
+
+  // ── Branch resolution ─────────────────────────────────────────────────────
+
+  _buildBranch() {
+    const byId = new Map(this._messages.map((m) => [m.messageId, m]));
+    const children = new Map();
+
+    for (const { messageId, parentId } of this._messages) {
+      const pid = parentId ?? "__root__";
+      (children.get(pid) ?? children.set(pid, []).get(pid)).push(messageId);
+    }
+
+    const branch = [];
+    let cursor = "__root__";
+
+    while (children.has(cursor)) {
+      const siblings = children.get(cursor);
+      const selected = this._siblingIndex[cursor];
+      const next =
+        selected && siblings.includes(selected)
+          ? selected
+          : siblings[siblings.length - 1];
+
+      const msg = byId.get(next);
+      if (!msg) break;
+      branch.push(msg);
+      cursor = msg.messageId;
+    }
+
+    return branch;
+  }
+
+  _emit(event, payload) {
+    for (const h of this._handlers[event] || []) h(payload);
+  }
+
+  close() {
+    for (const [event, ref] of this._channelRefs) this._channel.off(event, ref);
+    this._channelRefs = [];
+    this._handlers = {};
+  }
+}
+
+function authToken(value) {
+  const token = typeof value === "string" ? value : value?.auth;
+  if (!token || typeof token !== "string") {
+    throw new Error("Chat auth must return a JWT string or { auth: jwt }");
+  }
+  return token;
+}
+
+function invokeAuthCallback(callback, params) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const done = (error, value) => {
+      if (settled) return;
+      settled = true;
+      error ? reject(error) : resolve(value);
+    };
+
+    try {
+      const result = callback(params, done);
+      if (result?.then) result.then((value) => done(null, value), done);
+      else if (result !== undefined) done(null, result);
+    } catch (error) {
+      done(error);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// ActiveRun
+// ---------------------------------------------------------------------------
+
+export class ActiveRun {
+  constructor(runId, threadId, channel, meta = {}) {
+    this.runId = runId;
+    this._threadId = threadId;
+    this._channel = channel;
+    // Publish-ack metadata (ADR-0011): the codec-message-id the client owns
+    // for this send/edit, the fork/regenerate anchor, and the channel serial.
+    this.messageId = meta.messageId ?? null;
+    this.forkOf = meta.forkOf ?? null;
+    this.regeneratesMessageId = meta.regeneratesMessageId ?? null;
+    this.serial = meta.serial ?? null;
+    this.status = meta.status ?? "ok";
+  }
+
+  cancel() {
+    return new Promise((resolve, reject) => {
+      this._channel
+        .push("cancel", { runId: this.runId })
+        .receive("ok", resolve)
+        .receive("error", (e) =>
+          reject(new Error(e.reason || "cancel failed")),
+        );
+    });
+  }
+
+  toJSON() {
+    return { threadId: this._threadId, runId: this.runId };
+  }
+
+  toInvocation() {
+    return { toJSON: () => this.toJSON() };
+  }
+}