@forwardimpact/libbridge 0.1.0

package/src/callback-registry.js

@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+
+const DEFAULT_TTL_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * In-memory registry of pending bridge → workflow callbacks. Hosts persist
+ * the (token, correlationId) pairs via DiscussionContextStore so the registry
+ * can be rehydrated after a restart; this class only owns the live token →
+ * metadata mapping and TTL sweep.
+ */
+export class CallbackRegistry {
+  #ttlMs;
+  #entries = new Map();
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.ttlMs] - Time-to-live in ms (default: 2h)
+   */
+  constructor({ ttlMs = DEFAULT_TTL_MS } = {}) {
+    this.#ttlMs = ttlMs;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.#entries.size;
+  }
+
+  /**
+   * @param {string} correlationId
+   * @param {object} [meta] - Caller-defined metadata stored alongside the token
+   * @returns {string} The newly issued callback token
+   */
+  register(correlationId, meta = {}) {
+    if (typeof correlationId !== "string" || !correlationId) {
+      throw new Error("correlationId is required");
+    }
+    const token = randomUUID();
+    this.#entries.set(token, {
+      correlationId,
+      meta,
+      createdAt: Date.now(),
+    });
+    return token;
+  }
+
+  /**
+   * Atomic lookup + delete. Returns null if the token is unknown.
+   * @param {string} token
+   * @returns {{correlationId: string, meta: object, createdAt: number} | null}
+   */
+  consume(token) {
+    const entry = this.#entries.get(token);
+    if (!entry) return null;
+    this.#entries.delete(token);
+    return entry;
+  }
+
+  /**
+   * Returns a shallow clone of the stored metadata for a token without
+   * consuming it. Cloning prevents callers from corrupting internal state
+   * via the returned reference; diagnostic code paths that need to read
+   * `correlationId`, `meta`, or `createdAt` work unchanged.
+   * @param {string} token
+   * @returns {{correlationId: string, meta: object, createdAt: number} | null}
+   */
+  peek(token) {
+    const entry = this.#entries.get(token);
+    if (!entry) return null;
+    return { ...entry };
+  }
+
+  /**
+   * Drop entries older than ttlMs. Caller drives the clock so tests stay
+   * deterministic.
+   * @param {number} [now]
+   * @returns {number} Number of entries evicted
+   */
+  sweep(now = Date.now()) {
+    let evicted = 0;
+    for (const [token, entry] of this.#entries) {
+      if (now - entry.createdAt > this.#ttlMs) {
+        this.#entries.delete(token);
+        evicted++;
+      }
+    }
+    return evicted;
+  }
+}

package/src/discussion-context.js

@@ -0,0 +1,126 @@
+import { BufferedIndex } from "@forwardimpact/libindex";
+
+const DEFAULT_FLUSH_INTERVAL_MS = 5_000;
+const DEFAULT_MAX_BUFFER_SIZE = 1_000;
+const DEFAULT_CONVERSATION_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_SWEEP_INTERVAL_MS = 60_000;
+
+/**
+ * Persisted thread state keyed by `(channel, discussion_id)`. Both
+ * `services/ghbridge` and `services/msbridge` write into the same store so
+ * the channel-agnostic `kata-dispatch.yml` workflow can resume conversations
+ * from either side.
+ *
+ * Record shape:
+ *   {
+ *     id: "<channel>:<discussion_id>",
+ *     channel: "github-discussions" | "msteams",
+ *     discussion_id: string,
+ *     history: Array<{role: "user"|"assistant", text: string}>,
+ *     participants: Array<{name, kind: "agent"|"human", external_id?, metadata?}>,
+ *     open_rfcs: Record<correlationId, {trigger, opened_at, history_index_at_open}>,
+ *     lead: string,
+ *     pending_callbacks: Record<token, correlationId>,
+ *     last_active_at: number,
+ *   }
+ *
+ * @augments BufferedIndex
+ */
+export class DiscussionContextStore extends BufferedIndex {
+  #conversationTtlMs;
+  #sweepTimer;
+
+  /**
+   * @param {import("@forwardimpact/libstorage").StorageInterface} storage
+   * @param {object} [options]
+   * @param {string} [options.indexKey] - JSONL file name (default `discussions.jsonl`)
+   * @param {number} [options.flushIntervalMs]
+   * @param {number} [options.maxBufferSize]
+   * @param {number} [options.conversationTtlMs] - Eviction window (default 24h)
+   * @param {number} [options.sweepIntervalMs] - Sweep cadence (default 60s)
+   */
+  constructor(
+    storage,
+    {
+      indexKey = "discussions.jsonl",
+      flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS,
+      maxBufferSize = DEFAULT_MAX_BUFFER_SIZE,
+      conversationTtlMs = DEFAULT_CONVERSATION_TTL_MS,
+      sweepIntervalMs = DEFAULT_SWEEP_INTERVAL_MS,
+    } = {},
+  ) {
+    super(storage, indexKey, {
+      flush_interval: flushIntervalMs,
+      max_buffer_size: maxBufferSize,
+    });
+    this.#conversationTtlMs = conversationTtlMs;
+    this.#sweepTimer = setInterval(
+      () => this.#sweep(Date.now()),
+      sweepIntervalMs,
+    );
+    this.#sweepTimer.unref();
+  }
+
+  /**
+   * Compose the `id` field for a `(channel, discussion_id)` pair.
+   * @param {string} channel
+   * @param {string} discussionId
+   * @returns {string}
+   */
+  static keyOf(channel, discussionId) {
+    return `${channel}:${discussionId}`;
+  }
+
+  /**
+   * @param {string} channel
+   * @param {string} discussionId
+   * @returns {Promise<object | null>}
+   */
+  async loadByChannel(channel, discussionId) {
+    if (!this.loaded) await this.loadData();
+    const id = DiscussionContextStore.keyOf(channel, discussionId);
+    return this.index.get(id) ?? null;
+  }
+
+  /**
+   * Stop the periodic sweep timer. Called on host shutdown alongside
+   * `shutdown()` to release the interval.
+   */
+  stopSweep() {
+    if (this.#sweepTimer) {
+      clearInterval(this.#sweepTimer);
+      this.#sweepTimer = null;
+    }
+  }
+
+  /**
+   * Flush buffered writes and stop the sweep timer.
+   * @returns {Promise<void>}
+   */
+  async shutdown() {
+    this.stopSweep();
+    await super.shutdown();
+  }
+
+  /**
+   * Evict records whose `last_active_at` is older than `conversationTtlMs`.
+   * Caller-driven `now` keeps unit tests deterministic.
+   * @param {number} now
+   * @returns {number}
+   */
+  sweepNow(now) {
+    return this.#sweep(now);
+  }
+
+  #sweep(now) {
+    let evicted = 0;
+    for (const [id, record] of this.index) {
+      const lastActive = record?.last_active_at ?? 0;
+      if (now - lastActive > this.#conversationTtlMs) {
+        this.index.delete(id);
+        evicted++;
+      }
+    }
+    return evicted;
+  }
+}

package/src/dispatch.js

@@ -0,0 +1,66 @@
+/**
+ * Trigger a GitHub Actions `workflow_dispatch` for the channel-agnostic
+ * Kata dispatch workflow. Both `services/ghbridge` and `services/msbridge`
+ * route through this helper so the request body and headers stay byte-
+ * identical across bridges.
+ *
+ * Only includes `discussion_id` and `resume_context` in the `inputs` body
+ * when defined, so callers that omit them stay byte-identical to the legacy
+ * msteams dispatcher.
+ *
+ * @param {object} params
+ * @param {string} params.workflowFile - Workflow filename, e.g. `"kata-dispatch.yml"`
+ * @param {string} [params.ref] - Git ref to dispatch against (default `"main"`)
+ * @param {string} params.repo - `"owner/repo"`
+ * @param {string} params.token - GitHub installation/access token
+ * @param {string} params.prompt - The facilitator prompt
+ * @param {string} params.callbackUrl - Where the workflow posts the reply
+ * @param {string} params.correlationId - UUID linking dispatch → callback
+ * @param {string} [params.discussionId] - For trace linkage in libeval
+ * @param {string} [params.resumeContext] - JSON string carried across resumes
+ * @returns {Promise<void>}
+ */
+export async function dispatchWorkflow({
+  workflowFile,
+  ref = "main",
+  repo,
+  token,
+  prompt,
+  callbackUrl,
+  correlationId,
+  discussionId,
+  resumeContext,
+}) {
+  if (!workflowFile) throw new Error("workflowFile is required");
+  if (!repo) throw new Error("repo is required");
+  if (!token) throw new Error("token is required");
+
+  const inputs = {
+    prompt,
+    callback_url: callbackUrl,
+    correlation_id: correlationId,
+  };
+  if (discussionId !== undefined) inputs.discussion_id = discussionId;
+  if (resumeContext !== undefined) inputs.resume_context = resumeContext;
+
+  const url = `https://api.github.com/repos/${repo}/actions/workflows/${workflowFile}/dispatches`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ref, inputs }),
+  });
+
+  if (!res.ok) {
+    // GitHub's error body sometimes echoes the dispatched inputs, including
+    // the callback URL which carries a single-use token. Surface only the
+    // status — operators can inspect the run log if they need more.
+    throw new Error(
+      `workflow_dispatch failed: ${res.status} ${res.statusText}`,
+    );
+  }
+}

package/src/dispatcher.js

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+
+import { dispatchWorkflow } from "./dispatch.js";
+import { appendHistory } from "./history.js";
+
+/**
+ * The standard "dispatch dance" both bridges perform: generate a
+ * correlation ID, register the callback token, start the acknowledgement
+ * (if `ackTarget` is supplied), fire the kata-dispatch workflow, append
+ * history, push the dispatch timestamp, and flush the store. On failure
+ * the acknowledgement is finished and the callback registration is rolled
+ * back before the error rethrows.
+ *
+ * The caller still owns: loading/creating the context, checking the rate
+ * limiter, and deciding the user-facing action when `dispatch()` throws.
+ *
+ * @example
+ *   const { token, correlationId } = await dispatcher.dispatch({
+ *     ctx,
+ *     prompt,
+ *     ackTarget: { subjectId: nodeId },
+ *     historyText: text,
+ *     callbackMeta: { discussionId },
+ *     workflowInputs: { discussionId },
+ *   });
+ */
+export class Dispatcher {
+  #callbacks;
+  #ack;
+  #store;
+  #callbackBaseUrl;
+  #workflowFile;
+  #githubRepo;
+  #getGithubToken;
+
+  /**
+   * @param {object} options
+   * @param {import("./callback-registry.js").CallbackRegistry} options.callbacks
+   * @param {import("./acknowledgement.js").Acknowledgement} options.ack
+   * @param {import("./discussion-context.js").DiscussionContextStore} options.store
+   * @param {string} options.callbackBaseUrl - Already normalised
+   * @param {string} options.workflowFile
+   * @param {string} options.githubRepo
+   * @param {() => Promise<string> | string} options.getGithubToken
+   */
+  constructor({
+    callbacks,
+    ack,
+    store,
+    callbackBaseUrl,
+    workflowFile,
+    githubRepo,
+    getGithubToken,
+  }) {
+    if (!callbacks) throw new Error("callbacks is required");
+    if (!ack) throw new Error("ack is required");
+    if (!store) throw new Error("store is required");
+    if (typeof callbackBaseUrl !== "string") {
+      throw new Error("callbackBaseUrl is required");
+    }
+    if (!workflowFile) throw new Error("workflowFile is required");
+    if (!githubRepo) throw new Error("githubRepo is required");
+    if (typeof getGithubToken !== "function") {
+      throw new Error("getGithubToken is required");
+    }
+    this.#callbacks = callbacks;
+    this.#ack = ack;
+    this.#store = store;
+    this.#callbackBaseUrl = callbackBaseUrl;
+    this.#workflowFile = workflowFile;
+    this.#githubRepo = githubRepo;
+    this.#getGithubToken = getGithubToken;
+  }
+
+  /**
+   * @param {object} args
+   * @param {object} args.ctx - Discussion context record (mutated)
+   * @param {string} args.prompt
+   * @param {object} args.callbackMeta - Stored on the callback token
+   * @param {unknown} [args.ackTarget] - If omitted, no acknowledgement is started
+   * @param {string} [args.historyText] - Appended to ctx.history as the user turn on success
+   * @param {object} [args.workflowInputs] - Extra fields for `dispatchWorkflow`
+   * @returns {Promise<{token: string, correlationId: string}>}
+   */
+  async dispatch({
+    ctx,
+    prompt,
+    callbackMeta,
+    ackTarget,
+    historyText,
+    workflowInputs,
+  }) {
+    if (!ctx) throw new Error("ctx is required");
+    if (typeof prompt !== "string") throw new Error("prompt is required");
+
+    const correlationId = randomUUID();
+    const token = this.#callbacks.register(correlationId, callbackMeta ?? {});
+    ctx.pending_callbacks[token] = correlationId;
+    const callbackUrl = `${this.#callbackBaseUrl}/api/callback/${token}`;
+
+    if (ackTarget !== undefined) await this.#ack.start(token, ackTarget);
+    try {
+      const ghToken = await this.#getGithubToken();
+      await dispatchWorkflow({
+        workflowFile: this.#workflowFile,
+        repo: this.#githubRepo,
+        token: ghToken,
+        prompt,
+        callbackUrl,
+        correlationId,
+        ...(workflowInputs ?? {}),
+      });
+      if (historyText !== undefined) {
+        appendHistory(ctx.history, { role: "user", text: historyText });
+      }
+      ctx.dispatches.push(Date.now());
+      ctx.last_active_at = Date.now();
+      await this.#store.add(ctx);
+      await this.#store.flush();
+      return { token, correlationId };
+    } catch (err) {
+      if (ackTarget !== undefined) await this.#ack.finish(token, ackTarget);
+      this.#callbacks.consume(token);
+      delete ctx.pending_callbacks[token];
+      throw err;
+    }
+  }
+}

package/src/elapsed-scheduler.js

@@ -0,0 +1,82 @@
+const CHUNK_CAP_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * In-memory scheduler for `elapsed` resume triggers. JS `setTimeout`'s
+ * practical cap is ~24.8 days; this scheduler chunks longer durations
+ * into <= 7-day rearm segments so future >24-day windows work, while
+ * the persistent `due_at` in `open_rfcs` is the source of truth across
+ * restarts. Channel-agnostic — used by `ResumeScheduler` for both
+ * bridges.
+ */
+export class ElapsedScheduler {
+  #timers = new Map();
+  #onFire;
+  #onError;
+
+  /**
+   * @param {object} options
+   * @param {(correlationId: string) => Promise<void>} options.onFire - Invoked when the deadline passes.
+   * @param {(err: Error, correlationId: string) => void} [options.onError] - Invoked when `onFire` rejects.
+   */
+  constructor({ onFire, onError = () => {} }) {
+    if (typeof onFire !== "function") throw new Error("onFire is required");
+    this.#onFire = onFire;
+    this.#onError = onError;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.#timers.size;
+  }
+
+  /**
+   * Schedule a timer that fires at `dueAt` (absolute ms epoch).
+   * Replaces any existing timer for `correlationId`.
+   *
+   * @param {string} correlationId
+   * @param {number} dueAt
+   */
+  schedule(correlationId, dueAt) {
+    this.cancel(correlationId);
+    const remaining = dueAt - Date.now();
+    if (remaining <= 0) {
+      this.#fire(correlationId);
+      return;
+    }
+    const delay = Math.min(remaining, CHUNK_CAP_MS);
+    const timer = setTimeout(() => {
+      this.#timers.delete(correlationId);
+      if (remaining > CHUNK_CAP_MS) {
+        this.schedule(correlationId, dueAt);
+      } else {
+        this.#fire(correlationId);
+      }
+    }, delay);
+    timer.unref?.();
+    this.#timers.set(correlationId, timer);
+  }
+
+  /**
+   * Cancel the scheduled fire for `correlationId`. No-op if absent.
+   * @param {string} correlationId
+   */
+  cancel(correlationId) {
+    const timer = this.#timers.get(correlationId);
+    if (timer) {
+      clearTimeout(timer);
+      this.#timers.delete(correlationId);
+    }
+  }
+
+  /** Cancel every scheduled timer. */
+  clear() {
+    for (const timer of this.#timers.values()) clearTimeout(timer);
+    this.#timers.clear();
+  }
+
+  #fire(correlationId) {
+    this.#onFire(correlationId).catch((err) =>
+      this.#onError(err, correlationId),
+    );
+  }
+}

package/src/history.js

@@ -0,0 +1,14 @@
+/**
+ * Append a message to a bounded history, dropping the oldest entries when
+ * the cap is exceeded. Mutates `history` in place to match the legacy
+ * msteams bridge behaviour preserved in services/msbridge.
+ *
+ * @param {Array<{role: "user"|"assistant", text: string}>} history
+ * @param {{role: "user"|"assistant", text: string}} entry
+ * @param {object} [options]
+ * @param {number} [options.maxEntries] - Default 10
+ */
+export function appendHistory(history, entry, { maxEntries = 10 } = {}) {
+  history.push(entry);
+  while (history.length > maxEntries) history.shift();
+}

package/src/index.js

@@ -0,0 +1,38 @@
+/**
+ * Canonical configuration contract every bridge consumes. Channel-specific
+ * fields (e.g. `app_webhook_secret` on ghbridge, `msAppId()` on msbridge)
+ * extend this — see each bridge's README for the channel-specific surface.
+ *
+ * @typedef {object} BridgeConfig
+ * @property {string} host - Bind host (typically "127.0.0.1" or "0.0.0.0")
+ * @property {number} port - Bind port; 0 selects a free port
+ * @property {string} callback_base_url - Public URL the dispatched workflow posts back to
+ * @property {string} github_repo - "owner/repo" hosting the kata-dispatch workflow
+ */
+
+export { createBridgeServer } from "./server.js";
+export { CallbackRegistry } from "./callback-registry.js";
+export { buildPrompt } from "./prompt.js";
+export { appendHistory } from "./history.js";
+export { RateLimiter } from "./rate-limit.js";
+export { dispatchWorkflow } from "./dispatch.js";
+export { DiscussionContextStore } from "./discussion-context.js";
+export { ProgressTicker } from "./progress-ticker.js";
+export {
+  Acknowledgement,
+  DEFAULT_TYPING_VERBS,
+} from "./acknowledgement.js";
+export { Dispatcher } from "./dispatcher.js";
+export {
+  CallbackHandlerError,
+  createCallbackHandler,
+} from "./callback-handler.js";
+export { ElapsedScheduler } from "./elapsed-scheduler.js";
+export { ResumeScheduler } from "./resume-scheduler.js";
+export {
+  MAX_FIELD_LENGTH,
+  newDiscussionContext,
+  normalizeBaseUrl,
+  validateCallbackPayload,
+} from "./callback-payload.js";
+export { evaluateTrigger, parseIsoDuration } from "./triggers.js";

package/src/progress-ticker.js

@@ -0,0 +1,62 @@
+const DEFAULT_INTERVAL_MS = 25_000;
+
+/**
+ * Channel-agnostic ticker. Hosts call `start(token, tick)` after dispatching
+ * a workflow; `tick()` runs every `intervalMs` until the host calls
+ * `stop(token)` or until `tick()` rejects (which auto-stops the ticker —
+ * matching the legacy msteams ticker behaviour preserved in services/msbridge).
+ *
+ * Per-channel rendering (Teams typing activity, GitHub reaction) lives in
+ * the adapter; this class only owns the timer lifecycle.
+ */
+export class ProgressTicker {
+  #intervalMs;
+  #timers = new Map();
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.intervalMs] - Tick cadence in ms (default 12_000)
+   */
+  constructor({ intervalMs = DEFAULT_INTERVAL_MS } = {}) {
+    this.#intervalMs = intervalMs;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.#timers.size;
+  }
+
+  /**
+   * Start ticking for `token`. Replaces any existing ticker on the same
+   * token. Errors thrown by `tick` are swallowed and stop the ticker.
+   * @param {string} token
+   * @param {() => Promise<void> | void} tick
+   */
+  start(token, tick) {
+    if (typeof tick !== "function") {
+      throw new Error("tick must be a function");
+    }
+    this.stop(token);
+    const timer = setInterval(async () => {
+      try {
+        await tick();
+      } catch {
+        this.stop(token);
+      }
+    }, this.#intervalMs);
+    timer.unref?.();
+    this.#timers.set(token, timer);
+  }
+
+  /**
+   * Stop ticking for `token`. No-op if the token has no active ticker.
+   * @param {string} token
+   */
+  stop(token) {
+    const timer = this.#timers.get(token);
+    if (timer) {
+      clearInterval(timer);
+      this.#timers.delete(token);
+    }
+  }
+}

package/src/prompt.js

@@ -0,0 +1,30 @@
+/**
+ * Build a facilitator prompt from the current message text and a rolling
+ * conversation history. History is bounded to the last `maxExchanges`
+ * exchanges (2x entries) and the total prompt size is capped at `charCap`
+ * characters by dropping the oldest history entries until it fits.
+ *
+ * @param {string} text - The current user message
+ * @param {Array<{role: "user"|"assistant", text: string}>} history - Prior
+ *   exchanges in chronological order. Most recent last.
+ * @param {object} [options]
+ * @param {number} [options.maxExchanges] - Default 5 (10 entries kept)
+ * @param {number} [options.charCap] - Default 4000 characters total
+ * @returns {string}
+ */
+export function buildPrompt(
+  text,
+  history,
+  { maxExchanges = 5, charCap = 4000 } = {},
+) {
+  const trimmed = history.slice(-maxExchanges * 2);
+  while (trimmed.length > 0) {
+    const block = trimmed
+      .map((h) => `${h.role === "user" ? "User" : "Agent"}: ${h.text}`)
+      .join("\n\n");
+    const composed = `Prior conversation:\n${block}\n\nCurrent message: ${text}`;
+    if (composed.length <= charCap) return composed;
+    trimmed.shift();
+  }
+  return text;
+}

package/src/rate-limit.js

@@ -0,0 +1,45 @@
+/**
+ * Sliding-window rate limiter. Operates on a caller-owned `dispatches: number[]`
+ * array of timestamps and returns a structured result so callers can both
+ * gate dispatch and surface retry-after hints.
+ */
+export class RateLimiter {
+  #windowMs;
+  #max;
+
+  /**
+   * @param {object} [options]
+   * @param {number} [options.windowMs] - Sliding window length in ms (default: 60_000)
+   * @param {number} [options.max] - Max dispatches allowed in the window (default: 5)
+   */
+  constructor({ windowMs = 60_000, max = 5 } = {}) {
+    this.#windowMs = windowMs;
+    this.#max = max;
+  }
+
+  /**
+   * Evaluate rate-limit state for a thread. Mutates `dispatches` to drop
+   * timestamps outside the window before measuring.
+   *
+   * @param {string} threadId - For diagnostic/host bookkeeping; unused here.
+   * @param {number[]} dispatches - Caller-owned timestamps in ms epoch.
+   * @returns {{ allowed: boolean, retryAfterMs?: number }}
+   */
+  check(threadId, dispatches) {
+    if (!Array.isArray(dispatches)) {
+      throw new Error("dispatches must be an array");
+    }
+    const now = Date.now();
+    const cutoff = now - this.#windowMs;
+    let i = 0;
+    while (i < dispatches.length && dispatches[i] < cutoff) i++;
+    if (i > 0) dispatches.splice(0, i);
+
+    if (dispatches.length < this.#max) {
+      return { allowed: true };
+    }
+    const oldest = dispatches[0];
+    const retryAfterMs = Math.max(0, oldest + this.#windowMs - now);
+    return { allowed: false, retryAfterMs };
+  }
+}