@forwardimpact/libbridge 0.1.0

package/src/resume-scheduler.js

@@ -0,0 +1,254 @@
+import { ElapsedScheduler } from "./elapsed-scheduler.js";
+import { evaluateTrigger, parseIsoDuration } from "./triggers.js";
+
+const DEFAULT_PROMPT = "Resume requested.";
+
+/**
+ * Channel-agnostic suspend/resume lifecycle for the discuss-mode trace.
+ * When the workflow returns a `"recessed"` verdict, the bridge calls
+ * `enterRecess(...)` to persist the trigger on
+ * `ctx.open_rfcs[correlationId]`. The scheduler watches inbound activity
+ * via `processInbound(ctx)` and ticking elapsed timers via the embedded
+ * `ElapsedScheduler`; when a trigger fires, it redispatches the workflow
+ * through the shared `Dispatcher` with a `resume_context` payload
+ * linking back to the original correlation id.
+ *
+ * Channel-specific extras are supplied by two small constructor
+ * callbacks:
+ *
+ *   buildCallbackMeta(ctx) -> { ... }   // matches the bridge's loadDiscussionId
+ *   buildResumeInputs(ctx) -> { ... }   // extra workflow_dispatch inputs
+ *
+ * Both default to ghbridge's convention; msbridge overrides
+ * `buildCallbackMeta` to `{ threadId: ctx.discussion_id }` when it
+ * adopts resume.
+ *
+ * @example
+ *   const scheduler = new ResumeScheduler({
+ *     dispatcher,
+ *     store,
+ *     logger,
+ *     buildCallbackMeta: (ctx) => ({ discussionId: ctx.discussion_id }),
+ *     buildResumeInputs: (ctx) => ({ discussionId: ctx.discussion_id }),
+ *   });
+ *   // service start:
+ *   await scheduler.rearm();
+ *   // inbound activity:
+ *   const { freshDispatchAllowed } = await scheduler.processInbound(ctx);
+ *   if (freshDispatchAllowed) { ... dispatch fresh ... }
+ *   // on "recessed" verdict:
+ *   scheduler.enterRecess(ctx, correlationId, payload.trigger);
+ *   // on "adjourned" / "failed":
+ *   scheduler.cancelRecess(ctx, correlationId);
+ *   // service stop:
+ *   scheduler.clear();
+ */
+export class ResumeScheduler {
+  #dispatcher;
+  #store;
+  #logger;
+  #elapsed;
+  #prompt;
+  #buildResumeInputs;
+  #buildCallbackMeta;
+
+  /**
+   * @param {object} options
+   * @param {import("./dispatcher.js").Dispatcher} options.dispatcher
+   * @param {import("./discussion-context.js").DiscussionContextStore} options.store
+   * @param {{error?: Function, info?: Function}} [options.logger]
+   * @param {string} [options.prompt] - Default "Resume requested."
+   * @param {(ctx: object) => object} [options.buildCallbackMeta]
+   * @param {(ctx: object) => object} [options.buildResumeInputs]
+   */
+  constructor({
+    dispatcher,
+    store,
+    logger,
+    prompt = DEFAULT_PROMPT,
+    buildCallbackMeta = (ctx) => ({ discussionId: ctx.discussion_id }),
+    buildResumeInputs = () => ({}),
+  }) {
+    if (!dispatcher) throw new Error("dispatcher is required");
+    if (!store) throw new Error("store is required");
+    if (typeof buildCallbackMeta !== "function") {
+      throw new Error("buildCallbackMeta must be a function");
+    }
+    if (typeof buildResumeInputs !== "function") {
+      throw new Error("buildResumeInputs must be a function");
+    }
+    this.#dispatcher = dispatcher;
+    this.#store = store;
+    this.#logger = logger ?? null;
+    this.#prompt = prompt;
+    this.#buildCallbackMeta = buildCallbackMeta;
+    this.#buildResumeInputs = buildResumeInputs;
+    this.#elapsed = new ElapsedScheduler({
+      onFire: (cid) => this.#fireElapsed(cid),
+      onError: (err, cid) =>
+        this.#logger?.error?.("resume.elapsed", err, {
+          correlation_id: cid,
+        }),
+    });
+  }
+
+  /** @returns {number} Number of armed elapsed timers */
+  get size() {
+    return this.#elapsed.size;
+  }
+
+  /**
+   * Begin watching `correlationId` for trigger resolution. Persists the
+   * trigger and the history index at recess time onto
+   * `ctx.open_rfcs[correlationId]`. If the trigger has an elapsed
+   * component, schedules an in-memory timer that will fire even when no
+   * inbound activity arrives. No-op if `trigger` is falsy.
+   *
+   * The caller is responsible for flushing the store after this call —
+   * `enterRecess` mutates ctx but does not write.
+   *
+   * @param {object} ctx
+   * @param {string} correlationId
+   * @param {import("./triggers.js").ResumeTrigger} trigger
+   */
+  enterRecess(ctx, correlationId, trigger) {
+    if (!trigger) return;
+    const openedAt = Date.now();
+    ctx.open_rfcs[correlationId] = {
+      trigger,
+      opened_at: openedAt,
+      history_index_at_open: ctx.history.length,
+    };
+    if (trigger.kind === "elapsed" || trigger.kind === "either") {
+      if (typeof trigger.elapsed === "string") {
+        const dueAt = openedAt + parseIsoDuration(trigger.elapsed);
+        ctx.open_rfcs[correlationId].due_at = dueAt;
+        this.#elapsed.schedule(correlationId, dueAt);
+      }
+    }
+  }
+
+  /**
+   * Stop watching `correlationId`. Removes the rfc from `ctx.open_rfcs`
+   * and cancels any associated elapsed timer. Idempotent — safe to call
+   * for verdicts that didn't actually recess.
+   *
+   * @param {object} ctx
+   * @param {string} correlationId
+   */
+  cancelRecess(ctx, correlationId) {
+    delete ctx.open_rfcs[correlationId];
+    this.#elapsed.cancel(correlationId);
+  }
+
+  /**
+   * Walk `ctx.open_rfcs`. For each rfc whose trigger has fired given the
+   * current history length and clock, redispatch the workflow with
+   * `resume_context` linking back to the original correlation id, then
+   * cancel the rfc. Returns a summary so the host can decide whether to
+   * additionally fire a fresh lead session on this inbound activity.
+   *
+   * If a redispatch fails the rfc remains armed — the host's failure
+   * recovery (next inbound activity, or the next elapsed tick) will
+   * retry.
+   *
+   * @param {object} ctx
+   * @returns {Promise<{
+   *   fired: number,
+   *   hasOpenRfc: boolean,
+   *   freshDispatchAllowed: boolean,
+   * }>}
+   */
+  async processInbound(ctx) {
+    const fired = this.#evaluate(ctx);
+    for (const { correlationId, rfc } of fired) {
+      const historySince = ctx.history.slice(rfc.history_index_at_open);
+      await this.#redispatch(ctx, correlationId, historySince);
+      this.cancelRecess(ctx, correlationId);
+    }
+    const hasOpenRfc = Object.keys(ctx.open_rfcs ?? {}).length > 0;
+    return {
+      fired: fired.length,
+      hasOpenRfc,
+      freshDispatchAllowed: fired.length === 0 && !hasOpenRfc,
+    };
+  }
+
+  /**
+   * Rehydrate persistent elapsed timers from the store. Call once after
+   * the bridge server starts so deadlines set before a restart still
+   * fire.
+   * @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);
+        }
+      }
+    }
+  }
+
+  /** Cancel every armed elapsed timer. Safe to call on shutdown. */
+  clear() {
+    this.#elapsed.clear();
+  }
+
+  #evaluate(ctx) {
+    const fired = [];
+    for (const [correlationId, rfc] of Object.entries(ctx.open_rfcs ?? {})) {
+      const trigger = rfc.trigger;
+      if (!trigger) continue;
+      const observed = {
+        responses: ctx.history.length - rfc.history_index_at_open,
+        opened_at: rfc.opened_at,
+      };
+      if (evaluateTrigger(trigger, observed, Date.now()).fired) {
+        fired.push({ correlationId, rfc });
+      }
+    }
+    return fired;
+  }
+
+  async #redispatch(ctx, correlationId, historySince) {
+    const resumeContext = JSON.stringify({
+      correlation_id: correlationId,
+      history_since: historySince,
+    });
+    await this.#dispatcher.dispatch({
+      ctx,
+      prompt: this.#prompt,
+      callbackMeta: this.#buildCallbackMeta(ctx),
+      workflowInputs: {
+        ...this.#buildResumeInputs(ctx),
+        resumeContext,
+      },
+    });
+  }
+
+  async #fireElapsed(correlationId) {
+    const found = await this.#findContextWithRfc(correlationId);
+    if (!found) return;
+    const { ctx, rfc } = found;
+    const historySince = ctx.history.slice(rfc.history_index_at_open);
+    await this.#redispatch(ctx, correlationId, historySince);
+    this.cancelRecess(ctx, correlationId);
+    ctx.last_active_at = Date.now();
+    await this.#store.add(ctx);
+    await this.#store.flush();
+  }
+
+  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;
+  }
+}

package/src/server.js

@@ -0,0 +1,105 @@
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+
+/**
+ * Create the channel-agnostic HTTP server that bridges (ghbridge, msbridge)
+ * share. The server mounts two routes:
+ *   - `OPTIONS|POST <webhookPath>` — channel-specific intake. The raw POST
+ *     body is captured on `c.get("rawBody")` for signature verification.
+ *   - `POST /api/callback/:token` — workflow → bridge reply intake.
+ *
+ * Handlers receive Hono's context `c` (matching the monorepo standard) and
+ * return a `Response` (or use `c.json` / `c.text` / `c.body`). The caller
+ * owns lifecycle (start/stop). Returning the `app` exposes the underlying
+ * Hono instance so adapters can mount additional health or diagnostic
+ * routes. `address()` returns the bound `{ port }` once started (useful for
+ * tests that bind to port 0).
+ *
+ * @param {object} options
+ * @param {{host?: string, port: number}} options.config - host/port
+ * @param {object} options.logger
+ * @param {object} [options.tracer]
+ * @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
+ * @returns {{ start: () => Promise<void>, stop: () => Promise<void>, app: import("hono").Hono, address: () => ({port: number} | null) }}
+ */
+export function createBridgeServer({
+  config,
+  logger,
+  tracer: _tracer,
+  webhookPath,
+  onWebhook,
+  onCallback,
+}) {
+  if (!config) throw new Error("config is required");
+  if (!logger) throw new Error("logger is required");
+  if (!webhookPath) throw new Error("webhookPath is required");
+  if (typeof onWebhook !== "function") {
+    throw new Error("onWebhook is required");
+  }
+  if (typeof onCallback !== "function") {
+    throw new Error("onCallback is required");
+  }
+
+  const app = new Hono();
+
+  // Capture the raw POST body once, before downstream handlers parse it.
+  // Channel adapters use this buffer to verify HMAC signatures.
+  app.use("*", async (c, next) => {
+    if (c.req.method === "POST") {
+      const buf = Buffer.from(await c.req.raw.clone().arrayBuffer());
+      c.set("rawBody", buf);
+    }
+    await next();
+  });
+
+  app.options(webhookPath, (c) => c.body(null, 200));
+
+  app.post(webhookPath, async (c) => {
+    try {
+      return await onWebhook(c);
+    } catch (err) {
+      logger.error("bridge.webhook", err);
+      return c.json({ error: "Webhook failure" }, 500);
+    }
+  });
+
+  app.post("/api/callback/:token", async (c) => {
+    try {
+      return await onCallback(c);
+    } catch (err) {
+      logger.error("bridge.callback", err);
+      return c.json({ error: "Callback failure" }, 500);
+    }
+  });
+
+  let server = null;
+
+  return {
+    app,
+    address() {
+      if (!server || typeof server.address !== "function") return null;
+      const addr = server.address();
+      if (!addr || typeof addr === "string") return null;
+      return { port: addr.port };
+    },
+    async start() {
+      const { host, port } = config;
+      await new Promise((resolve) => {
+        server = serve({ fetch: app.fetch, port, hostname: host }, (info) => {
+          logger.info("bridge.server", "listening", {
+            host,
+            port: info?.port ?? port,
+          });
+          resolve();
+        });
+      });
+    },
+    async stop() {
+      if (!server) return;
+      await new Promise((resolve) => server.close(() => resolve()));
+      server = null;
+    },
+  };
+}

package/src/triggers.js

@@ -0,0 +1,105 @@
+/**
+ * @typedef {object} ResumeTrigger
+ * @property {"responses"|"elapsed"|"either"} kind
+ * @property {number} [responses] - Number of new responses needed.
+ *   For `kind: "either"`, optional alongside `elapsed`.
+ * @property {string} [elapsed] - ISO-8601 duration, e.g. `"P14D"`, `"PT12H"`,
+ *   `"P1DT6H"`. Required for `kind: "elapsed"`; optional for `"either"`.
+ */
+
+const ISO_8601_DURATION =
+  /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+const MS_IN_SECOND = 1000;
+const MS_IN_MINUTE = 60 * MS_IN_SECOND;
+const MS_IN_HOUR = 60 * MS_IN_MINUTE;
+const MS_IN_DAY = 24 * MS_IN_HOUR;
+
+/**
+ * Parse an ISO-8601 duration into milliseconds. Supports the day/hour/
+ * minute/second subset used by the resume-trigger contract.
+ *
+ * @param {string} duration - e.g. `"P14D"`, `"PT12H"`, `"P1DT6H"`, `"PT30M"`
+ * @returns {number} Duration in milliseconds
+ */
+export function parseIsoDuration(duration) {
+  if (typeof duration !== "string" || !duration) {
+    throw new Error("duration must be a non-empty ISO-8601 string");
+  }
+  const match = ISO_8601_DURATION.exec(duration);
+  if (!match || duration === "P" || duration === "PT") {
+    throw new Error(`Unsupported ISO-8601 duration: ${duration}`);
+  }
+  const [, days, hours, minutes, seconds] = match;
+  return (
+    (Number(days) || 0) * MS_IN_DAY +
+    (Number(hours) || 0) * MS_IN_HOUR +
+    (Number(minutes) || 0) * MS_IN_MINUTE +
+    (Number(seconds) || 0) * MS_IN_SECOND
+  );
+}
+
+/**
+ * Evaluate whether a resume trigger has fired.
+ *
+ * @param {ResumeTrigger} trigger
+ * @param {{responses?: number, opened_at?: number}} observed
+ * @param {number} now - ms epoch (caller-provided for testability)
+ * @returns {{fired: boolean, due_at?: number}}
+ */
+export function evaluateTrigger(trigger, observed, now) {
+  if (!trigger || typeof trigger !== "object") {
+    throw new Error("trigger is required");
+  }
+  if (typeof now !== "number" || Number.isNaN(now)) {
+    throw new Error("now must be a number (ms epoch)");
+  }
+  observed ??= {};
+
+  switch (trigger.kind) {
+    case "responses":
+      return evaluateResponses(trigger, observed);
+    case "elapsed":
+      return evaluateElapsed(trigger, observed, now);
+    case "either": {
+      const r =
+        trigger.responses !== undefined
+          ? evaluateResponses(trigger, observed)
+          : { fired: false };
+      const e =
+        trigger.elapsed !== undefined
+          ? evaluateElapsed(trigger, observed, now)
+          : { fired: false };
+      if (r.fired || e.fired) return { fired: true };
+      return e.due_at !== undefined
+        ? { fired: false, due_at: e.due_at }
+        : { fired: false };
+    }
+    default:
+      throw new Error(`Unsupported trigger kind: ${trigger.kind}`);
+  }
+}
+
+function evaluateResponses(trigger, observed) {
+  if (typeof trigger.responses !== "number" || trigger.responses < 1) {
+    throw new Error(
+      'trigger.responses must be a positive number for kind "responses"',
+    );
+  }
+  const seen = observed.responses ?? 0;
+  return { fired: seen >= trigger.responses };
+}
+
+function evaluateElapsed(trigger, observed, now) {
+  if (typeof trigger.elapsed !== "string") {
+    throw new Error(
+      'trigger.elapsed must be an ISO-8601 string for kind "elapsed"',
+    );
+  }
+  if (typeof observed.opened_at !== "number") {
+    return { fired: false };
+  }
+  const dueAt = observed.opened_at + parseIsoDuration(trigger.elapsed);
+  return now >= dueAt
+    ? { fired: true, due_at: dueAt }
+    : { fired: false, due_at: dueAt };
+}