@gorlitzer-labs/apiary 1.13.3

package/dist/chunk-PEB6HEFT.js

@@ -0,0 +1,606 @@
+import {
+  EventCategory,
+  MessageSchema,
+  createEvent
+} from "./chunk-BZ4VDWC2.js";
+
+// src/core/storage.ts
+import { writeFile, readFile } from "fs/promises";
+import { resolve, sep } from "path";
+import { homedir, tmpdir } from "os";
+function paginate(items, limit, cursor, key) {
+  let subset;
+  if (cursor != null) {
+    const cursorIdx = items.findIndex((item) => key(item) === cursor);
+    if (cursorIdx === -1) {
+      return { items: [], next_cursor: null, has_more: false };
+    }
+    subset = items.slice(0, cursorIdx);
+  } else {
+    subset = items;
+  }
+  const page = limit < subset.length ? subset.slice(-limit) : subset.slice();
+  page.reverse();
+  const has_more = subset.length > limit;
+  const next_cursor = has_more && page.length > 0 ? key(page[page.length - 1]) : null;
+  return { items: page, next_cursor, has_more };
+}
+function paginateByIndex(items, limit, cursor) {
+  const parsedCursor = cursor != null ? parseInt(cursor, 10) : items.length;
+  const endIdx = Number.isNaN(parsedCursor) ? items.length : parsedCursor;
+  const startIdx = Math.max(0, endIdx - limit);
+  const page = items.slice(startIdx, endIdx).reverse();
+  const has_more = startIdx > 0;
+  const next_cursor = has_more ? String(startIdx) : null;
+  return { items: page, next_cursor, has_more };
+}
+var InMemoryStorage = class {
+  _messages = /* @__PURE__ */ new Map();
+  _events = /* @__PURE__ */ new Map();
+  async addMessage(message) {
+    const list = this._messages.get(message.room_id) ?? [];
+    list.push(message);
+    this._messages.set(message.room_id, list);
+    return message;
+  }
+  async getMessage(room_id, message_id) {
+    const list = this._messages.get(room_id) ?? [];
+    return list.find((m) => m.id === message_id) ?? null;
+  }
+  async getMessages(room_id, limit = 30, cursor = null) {
+    const messages = this._messages.get(room_id) ?? [];
+    return paginate(messages, limit, cursor, (m) => m.id);
+  }
+  async searchMessages(room_id, query, limit = 10, cursor = null) {
+    const messages = this._messages.get(room_id) ?? [];
+    const q = query.toLowerCase();
+    const filtered = messages.filter(
+      (m) => m.content.toLowerCase().includes(q)
+    );
+    return paginate(filtered, limit, cursor, (m) => m.id);
+  }
+  async addEvent(event) {
+    const list = this._events.get(event.room_id) ?? [];
+    list.push(event);
+    this._events.set(event.room_id, list);
+  }
+  async getEvents(room_id, category = null, limit = 50, cursor = null) {
+    let events = this._events.get(room_id) ?? [];
+    if (category != null) {
+      events = events.filter((e) => e.category === category);
+    }
+    return paginateByIndex(events, limit, cursor);
+  }
+  async clearRoom(room_id) {
+    this._messages.delete(room_id);
+    this._events.delete(room_id);
+  }
+};
+var FileBackedStorage = class _FileBackedStorage extends InMemoryStorage {
+  _filePath;
+  constructor(filePath) {
+    super();
+    this._filePath = resolve(filePath);
+    const cwd = process.cwd();
+    const tmp = tmpdir();
+    const apiaryDir = resolve(homedir(), ".apiary");
+    if (!this._filePath.startsWith(cwd + sep) && !this._filePath.startsWith(tmp + sep) && !this._filePath.startsWith(apiaryDir + sep)) {
+      throw new Error(`FileBackedStorage path must be under ${cwd}, ${tmp}, or ${apiaryDir}`);
+    }
+  }
+  async addMessage(message) {
+    const result = await super.addMessage(message);
+    await this._flush();
+    return result;
+  }
+  async addEvent(event) {
+    await super.addEvent(event);
+    await this._flush();
+  }
+  async clearRoom(room_id) {
+    await super.clearRoom(room_id);
+    await this._flush();
+  }
+  async _flush() {
+    const data = {};
+    for (const [roomId, messages] of this._messages) {
+      if (!data[roomId]) data[roomId] = { messages: [], events: [] };
+      data[roomId].messages = messages;
+    }
+    for (const [roomId, events] of this._events) {
+      if (!data[roomId]) data[roomId] = { messages: [], events: [] };
+      data[roomId].events = events;
+    }
+    await writeFile(this._filePath, JSON.stringify(data, null, 2));
+  }
+  /** Load an existing file and return a FileBackedStorage that continues saving to it. */
+  static async load(filePath) {
+    const storage = new _FileBackedStorage(filePath);
+    const raw = await readFile(storage._filePath, "utf-8");
+    const data = JSON.parse(raw);
+    for (const [roomId, { messages, events }] of Object.entries(data)) {
+      storage._messages.set(
+        roomId,
+        messages.map((m) => ({ ...m, timestamp: new Date(m.timestamp) }))
+      );
+      storage._events.set(
+        roomId,
+        events.map((e) => rehydrateEvent(e))
+      );
+    }
+    return storage;
+  }
+};
+function rehydrateEvent(e) {
+  const event = { ...e, timestamp: new Date(e.timestamp) };
+  if ("message" in event && event.message) {
+    event.message = { ...event.message, timestamp: new Date(event.message.timestamp) };
+  }
+  return event;
+}
+
+// src/core/channel.ts
+var Channel = class {
+  participantId;
+  participantName;
+  subscriptions;
+  _room;
+  _queue = [];
+  _waiters = [];
+  _disconnected = false;
+  constructor(room, participantId, participantName, subscriptions) {
+    this._room = room;
+    this.participantId = participantId;
+    this.participantName = participantName;
+    this.subscriptions = subscriptions;
+  }
+  get roomId() {
+    return this._room.roomId;
+  }
+  /**
+   * Send a chat message from this participant.
+   *
+   * Persists the message to storage, broadcasts a `MessageSentEvent` to all
+   * participants (including the sender), and fires `MentionedEvent` for any
+   * `@name` or `@identifier` patterns found in the content.
+   *
+   * @param content     — message text (may be empty if image is provided)
+   * @param replyToId   — ID of the message being replied to (optional)
+   * @param image       — optional legacy image attachment
+   * @param attachments — optional array of typed attachments
+   * @param recipients  — if non-empty, this is a whisper: only these participant IDs (plus sender) receive it
+   */
+  async sendMessage(content, replyToId, image, attachments, recipients) {
+    if (this._disconnected) {
+      throw new Error("Channel is disconnected");
+    }
+    const message = MessageSchema.parse({
+      room_id: this._room.roomId,
+      sender_id: this.participantId,
+      sender_name: this.participantName,
+      content,
+      reply_to_id: replyToId ?? null,
+      recipients: recipients ?? [],
+      attachments: attachments ?? [],
+      image_url: image?.url ?? null,
+      image_mime_type: image?.mimeType ?? null,
+      image_size_bytes: image?.sizeBytes ?? null
+    });
+    await this._room._handleMessage(message);
+    return message;
+  }
+  /**
+   * Ping another participant for a status check.
+   *
+   * Creates a `PingedEvent` delivered to the target and all observers.
+   * Unlike @mentions, pings are non-blocking for active agents.
+   */
+  async ping(targetId) {
+    if (this._disconnected) {
+      throw new Error("Channel is disconnected");
+    }
+    await this._room._handlePing(this.participantId, this.participantName, targetId);
+  }
+  /**
+   * Emit a non-message activity event to the room.
+   *
+   * Use this for platform events: tool use indicators, mode changes, compaction
+   * notices, etc. The event is persisted and broadcast to all subscribed
+   * participants.
+   */
+  async emit(event) {
+    if (this._disconnected) {
+      throw new Error("Channel is disconnected");
+    }
+    await this._room._handleEvent(event);
+  }
+  /**
+   * Change which event categories this channel receives.
+   * Takes effect immediately — buffered events from unsubscribed categories
+   * are not retroactively removed.
+   */
+  updateSubscriptions(categories) {
+    this.subscriptions = categories;
+  }
+  /**
+   * Leave the room.
+   *
+   * @param silent — if true, suppresses the `ParticipantLeft` broadcast.
+   *                 Agents disconnect silently to avoid chat noise.
+   */
+  async disconnect(silent = false) {
+    if (!this._disconnected) {
+      this._disconnected = true;
+      const waiters = this._waiters;
+      this._waiters = [];
+      for (const w of waiters) {
+        w.reject(new Error("Channel disconnected"));
+      }
+      await this._room._disconnectChannel(this, silent);
+    }
+  }
+  /** @internal Called by Room to mark this channel as disconnected without removing from room maps. */
+  _markDisconnected() {
+    if (!this._disconnected) {
+      this._disconnected = true;
+      const waiters = this._waiters;
+      this._waiters = [];
+      for (const w of waiters) {
+        w.reject(new Error("Channel disconnected"));
+      }
+    }
+  }
+  /** @internal Called by Room to deliver an incoming event. Filters by subscription. */
+  _deliver(event) {
+    if (this._disconnected) return;
+    if (!this.subscriptions.has(event.category)) return;
+    if (this._waiters.length > 0) {
+      const waiter = this._waiters.shift();
+      waiter.resolve(event);
+    } else {
+      this._queue.push(event);
+    }
+  }
+  /**
+   * Receive the next event, waiting up to `timeoutMs`.
+   *
+   * Returns null if no event arrives within the timeout. Drains buffered events
+   * before waiting. Used by `EventMultiplexer` to fan-in events from multiple
+   * rooms into a single stream.
+   */
+  receive(timeoutMs) {
+    if (this._queue.length > 0) {
+      return Promise.resolve(this._queue.shift());
+    }
+    if (this._disconnected) {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve2) => {
+      let settled = false;
+      const waiter = {
+        resolve: (event) => {
+          if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            resolve2(event);
+          }
+        },
+        reject: () => {
+          if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            resolve2(null);
+          }
+        }
+      };
+      this._waiters.push(waiter);
+      const timer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          const idx = this._waiters.indexOf(waiter);
+          if (idx !== -1) this._waiters.splice(idx, 1);
+          resolve2(null);
+        }
+      }, timeoutMs);
+    });
+  }
+  /**
+   * Async iterator — yields events as they arrive.
+   *
+   * Used by `EventMultiplexer` to fan-in all room channels into a single stream.
+   * The iterator completes when the channel is disconnected.
+   *
+   * @example
+   * for await (const event of channel) {
+   *   console.log(event.type);
+   * }
+   */
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this._queue.length > 0) {
+          return Promise.resolve({
+            value: this._queue.shift(),
+            done: false
+          });
+        }
+        if (this._disconnected) {
+          return Promise.resolve({
+            value: void 0,
+            done: true
+          });
+        }
+        return new Promise((resolve2, reject) => {
+          this._waiters.push({
+            resolve: (event) => resolve2({ value: event, done: false }),
+            reject
+          });
+        });
+      }
+    };
+  }
+};
+
+// src/core/room.ts
+var ALL_CATEGORIES = /* @__PURE__ */ new Set([
+  EventCategory.MESSAGE,
+  EventCategory.PRESENCE,
+  EventCategory.ACTIVITY,
+  EventCategory.MENTION
+]);
+var RESERVED_MENTION_TOKENS = /* @__PURE__ */ new Set(["all"]);
+var Room = class {
+  roomId;
+  /** Direct access to the underlying storage. Useful for bulk reads. */
+  storage;
+  _channels = /* @__PURE__ */ new Map();
+  _participants = /* @__PURE__ */ new Map();
+  _observers = /* @__PURE__ */ new Set();
+  _nextObserverId = 0;
+  /**
+   * @param roomId  — stable identifier for this room (e.g. a UUID or slug)
+   * @param storage — storage backend; defaults to `InMemoryStorage`
+   */
+  constructor(roomId, storage) {
+    this.roomId = roomId;
+    this.storage = storage ?? new InMemoryStorage();
+  }
+  /**
+   * Connect a participant and return their channel.
+   */
+  async connect(participantId, name, options) {
+    const type = options?.type ?? "human";
+    const identifier = options?.identifier;
+    const subscribe = options?.subscribe;
+    const silent = options?.silent ?? false;
+    const authority = options?.authority;
+    if (RESERVED_MENTION_TOKENS.has(name.toLowerCase()) || identifier && RESERVED_MENTION_TOKENS.has(identifier.toLowerCase())) {
+      throw new Error(`Name or identifier cannot be a reserved mention token: ${RESERVED_MENTION_TOKENS}`);
+    }
+    const participant = {
+      id: participantId,
+      name,
+      status: "online",
+      type,
+      ...identifier ? { identifier } : {},
+      ...authority ? { authority } : {}
+    };
+    this._participants.set(participantId, participant);
+    const existingChannel = this._channels.get(participantId);
+    if (existingChannel) {
+      existingChannel._markDisconnected();
+    }
+    const subscriptions = subscribe ?? new Set(ALL_CATEGORIES);
+    const channel = new Channel(this, participantId, name, subscriptions);
+    this._channels.set(participantId, channel);
+    if (!silent) {
+      const event = createEvent({
+        type: "ParticipantJoined",
+        category: "PRESENCE",
+        room_id: this.roomId,
+        participant_id: participantId,
+        participant
+      });
+      await this._storeAndBroadcast(event, participantId);
+    }
+    return channel;
+  }
+  /**
+   * Observe all room events without being a participant.
+   *
+   * Returns a channel that receives every event — broadcasts AND targeted
+   * @mention events directed at other participants. Observers do NOT appear
+   * in `listParticipants()` and do not emit join/leave presence events,
+   * since they are not participants.
+   *
+   * Disconnect via `observer.disconnect()` when done.
+   *
+   * @example
+   * const observer = room.observe();
+   * for await (const event of observer) {
+   *   // sees everything, including mentions for other participants
+   * }
+   */
+  observe() {
+    const id = `__obs_${this.roomId}_${this._nextObserverId++}`;
+    const channel = new Channel(this, id, "__observer__", new Set(ALL_CATEGORIES));
+    this._observers.add(channel);
+    return channel;
+  }
+  // ── Read methods ───────────────────────────────────────────────────────────
+  /**
+   * Paginate messages, newest-first. Pass the returned `next_cursor` to get
+   * the next (older) page.
+   */
+  async listMessages(limit = 30, cursor = null) {
+    return this.storage.getMessages(this.roomId, limit, cursor);
+  }
+  /**
+   * Full-text search across message content, newest-first.
+   * `query` is matched case-insensitively against message content.
+   */
+  async searchMessages(query, limit = 10, cursor = null) {
+    return this.storage.searchMessages(this.roomId, query, limit, cursor);
+  }
+  /** All currently connected participants (including agents). Observers excluded. */
+  listParticipants() {
+    return [...this._participants.values()];
+  }
+  /**
+   * Paginate room events, newest-first.
+   * `category` optionally filters to one EventCategory.
+   */
+  async listEvents(category = null, limit = 50, cursor = null) {
+    return this.storage.getEvents(this.roomId, category, limit, cursor);
+  }
+  /** Look up a single message by ID. Returns null if not found. */
+  async getMessage(id) {
+    return this.storage.getMessage(this.roomId, id);
+  }
+  /** Update a participant's authority level at runtime. */
+  setParticipantAuthority(participantId, authority) {
+    const participant = this._participants.get(participantId);
+    if (!participant) return false;
+    participant.authority = authority;
+    return true;
+  }
+  // ── Internal methods (called by Channel) ──────────────────────────────────
+  /**
+   * @internal
+   * Store a message, broadcast MessageSentEvent, and fire MentionedEvents.
+   *
+   * @mention scanning: looks for `@token` patterns in content and matches
+   * against each connected participant's `identifier` and display `name`
+   * (case-insensitive). Fires a `MentionedEvent` for each match, delivered
+   * to the mentioned participant AND all observers.
+   */
+  async _handleMessage(message) {
+    await this.storage.addMessage(message);
+    const event = createEvent({
+      type: "MessageSent",
+      category: "MESSAGE",
+      room_id: this.roomId,
+      participant_id: message.sender_id,
+      message
+    });
+    await this._storeAndBroadcast(event);
+    const mentions = this._detectMentions(message.content);
+    for (const mentionedId of mentions) {
+      const ch = this._channels.get(mentionedId);
+      if (ch) {
+        const mentionEvent = createEvent({
+          type: "Mentioned",
+          category: "MENTION",
+          room_id: this.roomId,
+          participant_id: mentionedId,
+          message
+        });
+        await this.storage.addEvent(mentionEvent);
+        ch._deliver(mentionEvent);
+        for (const observer of this._observers) {
+          observer._deliver(mentionEvent);
+        }
+      }
+    }
+  }
+  /**
+   * @internal
+   * Send a ping to a participant. Creates a PingedEvent delivered to the
+   * target's channel and all observers (same routing as MentionedEvent).
+   */
+  async _handlePing(senderId, senderName, targetId) {
+    const ch = this._channels.get(targetId);
+    if (!ch) return;
+    const event = createEvent({
+      type: "Pinged",
+      category: "MENTION",
+      room_id: this.roomId,
+      participant_id: targetId,
+      pinger_id: senderId,
+      pinger_name: senderName
+    });
+    await this.storage.addEvent(event);
+    ch._deliver(event);
+    for (const observer of this._observers) {
+      observer._deliver(event);
+    }
+  }
+  /** @internal Store and broadcast an activity event. */
+  async _handleEvent(event) {
+    await this._storeAndBroadcast(event, event.participant_id);
+  }
+  /** @internal Remove a channel and optionally broadcast ParticipantLeftEvent. */
+  async _disconnectChannel(channel, silent = false) {
+    if (this._observers.delete(channel)) {
+      return;
+    }
+    const pid = channel.participantId;
+    const participant = this._participants.get(pid);
+    this._channels.delete(pid);
+    this._participants.delete(pid);
+    if (!silent && participant) {
+      const event = createEvent({
+        type: "ParticipantLeft",
+        category: "PRESENCE",
+        room_id: this.roomId,
+        participant_id: pid,
+        participant
+      });
+      await this._storeAndBroadcast(event);
+    }
+  }
+  async _storeAndBroadcast(event, exclude) {
+    await this.storage.addEvent(event);
+    this._broadcast(event, exclude);
+  }
+  _broadcast(event, exclude) {
+    for (const [pid, channel] of this._channels) {
+      if (pid !== exclude) {
+        channel._deliver(event);
+      }
+    }
+    for (const observer of this._observers) {
+      observer._deliver(event);
+    }
+  }
+  /**
+   * Scan message content for `@token` patterns and return matching participant IDs.
+   * Matches against both `identifier` (e.g. `@my-agent`) and display `name` (e.g. `@Alice`).
+   * Case-insensitive. Deduplicates — each participant appears at most once.
+   */
+  _detectMentions(content) {
+    const seen = /* @__PURE__ */ new Set();
+    const mentionedIds = [];
+    const pattern = /@([a-zA-Z0-9_-]+)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const token = match[1].toLowerCase();
+      if (token === "all") {
+        for (const [pid] of this._participants) {
+          if (!seen.has(pid)) {
+            seen.add(pid);
+            mentionedIds.push(pid);
+          }
+        }
+        continue;
+      }
+      for (const [pid, participant] of this._participants) {
+        const matchesId = participant.identifier?.toLowerCase() === token;
+        const matchesName = participant.name.toLowerCase() === token;
+        if ((matchesId || matchesName) && !seen.has(pid)) {
+          seen.add(pid);
+          mentionedIds.push(pid);
+        }
+      }
+    }
+    return mentionedIds;
+  }
+};
+
+export {
+  InMemoryStorage,
+  FileBackedStorage,
+  Channel,
+  Room
+};
+//# sourceMappingURL=chunk-PEB6HEFT.js.map