@forwardimpact/libbridge 0.1.4 → 0.1.6

package/README.md

@@ -13,7 +13,6 @@ Threaded-channel bridge primitives — relay messages between human channels
 import {
   createBridgeServer,
   CallbackRegistry,
-  DiscussionContextStore,
   RateLimiter,
   ProgressTicker,
   appendHistory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libbridge",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Threaded-channel bridge primitives — relay messages between human channels (GitHub Discussions, Microsoft Teams) and the Kata agent team.",
   "keywords": [
     "bridge",
@@ -40,8 +40,6 @@
     "test": "bun test test/*.test.js"
   },
   "dependencies": {
-    "@forwardimpact/libindex": "^0.1.38",
-    "@forwardimpact/libstorage": "^0.1.78",
     "@forwardimpact/libtype": "^0.1.0",
     "@hono/node-server": "^2.0.4",
     "hono": "^4.12.23"

package/src/callback-handler.js

@@ -37,7 +37,7 @@ export class CallbackHandlerError extends Error {
  * @param {string} options.channel
  * @param {import("./callback-registry.js").CallbackRegistry} options.callbacks
  * @param {import("./acknowledgement.js").Acknowledgement} options.ack
- * @param {import("./discussion-context.js").DiscussionContextStore} options.store
+ * @param {import("./index.js").DiscussionAdapter} options.store
  * @param {{debug?: Function, error?: Function}} options.logger
  * @param {{startSpan: Function}} options.tracer
  * @param {string} options.spanName

package/src/callback-registry.js

@@ -4,7 +4,7 @@ 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
+ * the (token, correlationId) pairs via the discussion store so the registry
  * can be rehydrated after a restart; this class only owns the live token →
  * metadata mapping and TTL sweep.
  */

package/src/dispatcher.js

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
 
 import { dispatchWorkflow } from "./dispatch.js";
-import { appendHistory } from "./history.js";
 
 /** Dispatch dance: resolve per-user token, register callback, ack, fire workflow, flush. */
 export class Dispatcher {
@@ -17,7 +16,7 @@ export class Dispatcher {
    * @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 {import("./index.js").DiscussionAdapter} options.store
    * @param {string} options.callbackBaseUrl - Already normalised
    * @param {string} options.workflowFile
    * @param {string} options.githubRepo
@@ -57,7 +56,6 @@ export class Dispatcher {
    * @param {string} args.requester - Surface user id of the triggering human
    * @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<{kind: "dispatched", token: string, correlationId: string} | {kind: "link_required", authorizeUrl: string} | {kind: "reauth_required"} | {kind: "transient", error: Error}>}
    */
@@ -67,7 +65,6 @@ export class Dispatcher {
     requester,
     callbackMeta,
     ackTarget,
-    historyText,
     workflowInputs,
   }) {
     if (!ctx) throw new Error("ctx is required");
@@ -94,9 +91,6 @@ export class Dispatcher {
         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);

package/src/history.js

@@ -9,6 +9,8 @@
  * @param {number} [options.maxEntries] - Default 10
  */
 export function appendHistory(history, entry, { maxEntries = 10 } = {}) {
-  history.push(entry);
+  const record = { role: entry.role, text: entry.text };
+  if (entry.author !== undefined) record.author = entry.author;
+  history.push(record);
   while (history.length > maxEntries) history.shift();
 }

package/src/index.js

@@ -10,14 +10,24 @@
  * @property {string} github_repo - "owner/repo" hosting the kata-dispatch workflow
  */
 
+/**
+ * @typedef {object} DiscussionAdapter
+ * @property {(channel: string, discussionId: string) => Promise<object|null>} loadByChannel
+ * @property {(correlationId: string) => Promise<object|null>} loadByCorrelation
+ * @property {() => Promise<Array<{correlationId: string, dueAt: number}>>} listOpenRecesses
+ * @property {(ctx: object) => Promise<void>} add
+ * @property {() => Promise<void>} flush
+ * @property {() => Promise<void>} shutdown
+ * @property {(target: object) => Promise<void>} [putPendingDispatch]
+ * @property {(linkToken: string) => Promise<object|null>} [resolvePendingDispatch]
+ */
+
 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 { OriginIndex } from "./origin-index.js";
 export { ProgressTicker } from "./progress-ticker.js";
 export {
   Acknowledgement,
@@ -39,3 +49,4 @@ export {
   validateCallbackPayload,
 } from "./callback-payload.js";
 export { evaluateTrigger, parseIsoDuration } from "./triggers.js";
+export { prepareLinkResume, createLinkCompleteHandler } from "./link-resume.js";

package/src/link-resume.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import { normalizeBaseUrl } from "./callback-payload.js";
+import { buildPrompt } from "./prompt.js";
+
+/**
+ * @param {string} authorizeUrl
+ * @param {string} callbackBaseUrl
+ * @returns {{ linkToken: string, augmentedUrl: string }}
+ */
+export function prepareLinkResume(authorizeUrl, callbackBaseUrl) {
+  const linkToken = randomUUID();
+  const url = new URL(authorizeUrl);
+  url.searchParams.set(
+    "redirect_uri",
+    `${normalizeBaseUrl(callbackBaseUrl)}/api/link-complete`,
+  );
+  url.searchParams.set("client_state", linkToken);
+  return { linkToken, augmentedUrl: url.toString() };
+}
+
+/**
+ * @param {object} options
+ * @returns {(c: import("hono").Context) => Promise<Response>}
+ */
+export function createLinkCompleteHandler({
+  channel,
+  store,
+  dispatcher,
+  buildCallbackMeta,
+}) {
+  return async (c) => {
+    const linkToken = c.req.query("state");
+    if (!linkToken) {
+      return c.html(
+        "<!DOCTYPE html><html><body><h1>Error</h1>" +
+          "<p>Missing state parameter.</p></body></html>",
+        400,
+      );
+    }
+
+    const target = await store.resolvePendingDispatch(linkToken);
+    if (!target) {
+      return c.html(
+        "<!DOCTYPE html><html><body><h1>Already processed</h1>" +
+          "<p>This link has already been used or has expired." +
+          "</p></body></html>",
+      );
+    }
+
+    const ctx = await store.loadByChannel(channel, target.discussion_id);
+    if (!ctx) {
+      return c.html(
+        "<!DOCTYPE html><html><body><h1>Error</h1>" +
+          "<p>Discussion not found.</p></body></html>",
+        404,
+      );
+    }
+
+    const userTurn = [...ctx.history]
+      .reverse()
+      .find((e) => e.role === "user" && e.author === target.surface_user_id);
+    if (!userTurn) {
+      return c.html(
+        "<!DOCTYPE html><html><body><h1>Error</h1>" +
+          "<p>No message found to re-dispatch.</p></body></html>",
+        404,
+      );
+    }
+
+    const result = await dispatcher.dispatch({
+      ctx,
+      prompt: buildPrompt(userTurn.text, ctx.history),
+      requester: target.surface_user_id,
+      callbackMeta: buildCallbackMeta(ctx),
+      workflowInputs: { discussionId: target.discussion_id },
+    });
+
+    if (result.kind === "dispatched") {
+      return c.html(
+        "<!DOCTYPE html><html><body><h1>Processing</h1>" +
+          "<p>Your message is being processed. " +
+          "You can close this window.</p></body></html>",
+      );
+    }
+
+    return c.html(
+      "<!DOCTYPE html><html><body><h1>Unable to dispatch</h1>" +
+        "<p>Your account could not be verified. Please try " +
+        "linking again from the conversation.</p></body></html>",
+    );
+  };
+}

package/src/resume-scheduler.js

@@ -17,7 +17,7 @@ export class ResumeScheduler {
   /**
    * @param {object} options
    * @param {import("./dispatcher.js").Dispatcher} options.dispatcher
-   * @param {import("./discussion-context.js").DiscussionContextStore} options.store
+   * @param {import("./index.js").DiscussionAdapter} options.store
    * @param {{error?: Function, info?: Function}} [options.logger]
    * @param {string} [options.prompt] - Default "Resume requested."
    * @param {(ctx: object) => object} [options.buildCallbackMeta]
@@ -137,15 +137,9 @@ export class ResumeScheduler {
    * @returns {Promise<void>}
    */
   async rearm() {
-    if (!this.#store.loaded) await this.#store.loadData();
-    for (const record of this.#store.index.values()) {
-      const open = record?.open_rfcs;
-      if (!open) continue;
-      for (const [correlationId, rfc] of Object.entries(open)) {
-        if (typeof rfc.due_at === "number") {
-          this.#elapsed.schedule(correlationId, rfc.due_at);
-        }
-      }
+    const refs = await this.#store.listOpenRecesses();
+    for (const { correlationId, dueAt } of refs) {
+      this.#elapsed.schedule(correlationId, dueAt);
     }
   }
 
@@ -220,12 +214,8 @@ export class ResumeScheduler {
   }
 
   async #findContextWithRfc(correlationId) {
-    if (!this.#store.loaded) await this.#store.loadData();
-    for (const record of this.#store.index.values()) {
-      if (record?.open_rfcs?.[correlationId]) {
-        return { ctx: record, rfc: record.open_rfcs[correlationId] };
-      }
-    }
-    return null;
+    const ctx = await this.#store.loadByCorrelation(correlationId);
+    if (!ctx) return null;
+    return { ctx, rfc: ctx.open_rfcs[correlationId] };
   }
 }

package/src/server.js

@@ -23,6 +23,7 @@ import { serve } from "@hono/node-server";
  * @param {string} options.webhookPath - e.g. `/api/messages` or `/api/webhooks/github`
  * @param {(c: import("hono").Context) => Promise<Response> | Response} options.onWebhook
  * @param {(c: import("hono").Context) => Promise<Response> | Response} options.onCallback
+ * @param {((c: import("hono").Context) => Promise<Response> | Response)} [options.onLinkComplete]
  * @returns {{ start: () => Promise<void>, stop: () => Promise<void>, app: import("hono").Hono, address: () => ({port: number} | null) }}
  */
 export function createBridgeServer({
@@ -32,6 +33,7 @@ export function createBridgeServer({
   webhookPath,
   onWebhook,
   onCallback,
+  onLinkComplete,
 }) {
   if (!config) throw new Error("config is required");
   if (!logger) throw new Error("logger is required");
@@ -86,6 +88,17 @@ export function createBridgeServer({
     }
   });
 
+  if (onLinkComplete) {
+    app.get("/api/link-complete", async (c) => {
+      try {
+        return await onLinkComplete(c);
+      } catch (err) {
+        logger.error("bridge.link-complete", err);
+        return c.json({ error: "Link completion failure" }, 500);
+      }
+    });
+  }
+
   let server = null;
 
   return {

package/src/discussion-context.js

@@ -1,126 +0,0 @@
-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/origin-index.js

@@ -1,49 +0,0 @@
-import { BufferedIndex } from "@forwardimpact/libindex";
-
-const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
-
-/**
- * Tracks comment IDs posted by the bridge so webhook handlers can skip
- * dispatching for self-originated events. Wraps `BufferedIndex` with
- * caller-injected `StorageInterface` per the libbridge invariant.
- *
- * Record shape: `{ id: "<comment_node_id>", discussion_id, posted_at }`
- *
- * @augments BufferedIndex
- */
-export class OriginIndex extends BufferedIndex {
-  #ttlMs;
-
-  /**
-   * @param {import("@forwardimpact/libstorage").StorageInterface} storage
-   * @param {object} [options]
-   * @param {string} [options.indexKey]
-   * @param {number} [options.ttlMs] - Eviction window (default 24h)
-   */
-  constructor(
-    storage,
-    { indexKey = "origins.jsonl", ttlMs = DEFAULT_TTL_MS } = {},
-  ) {
-    super(storage, indexKey, {
-      flush_interval: 1_000,
-      max_buffer_size: 100,
-    });
-    this.#ttlMs = ttlMs;
-  }
-
-  /**
-   * Evict records older than `ttlMs`.
-   * @param {number} now
-   * @returns {number} count evicted
-   */
-  sweep(now) {
-    let evicted = 0;
-    for (const [id, record] of this.index) {
-      if (now - (record?.posted_at ?? 0) > this.#ttlMs) {
-        this.index.delete(id);
-        evicted++;
-      }
-    }
-    return evicted;
-  }
-}