@forwardimpact/libbridge 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libbridge",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Threaded-channel bridge primitives — relay messages between human channels (GitHub Discussions, Microsoft Teams) and the Kata agent team.",
   "keywords": [
     "bridge",
@@ -42,11 +42,12 @@
   "dependencies": {
     "@forwardimpact/libindex": "^0.1.38",
     "@forwardimpact/libstorage": "^0.1.78",
-    "@hono/node-server": "^2.0.3",
-    "hono": "^4.12.22"
+    "@forwardimpact/libtype": "^0.1.0",
+    "@hono/node-server": "^2.0.4",
+    "hono": "^4.12.23"
   },
   "devDependencies": {
-    "@forwardimpact/libharness": "^0.1.21"
+    "@forwardimpact/libmock": "^0.1.0"
   },
   "engines": {
     "bun": ">=1.2.0",

package/src/callback-payload.js

@@ -48,7 +48,20 @@ export function validateCallbackPayload(body) {
   };
 }
 
-const ALLOWED_TRIGGER_KINDS = new Set(["responses", "elapsed", "any"]);
+const ALLOWED_TRIGGER_KINDS = new Set([
+  "missing_input",
+  "escalation_needed",
+  "elapsed",
+]);
+
+const TRIGGER_FIELD_VALIDATORS = {
+  replies: (raw) => {
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+  },
+  elapsed: (raw) => (typeof raw === "string" ? raw : undefined),
+  signal: (raw) => (typeof raw === "string" && raw ? raw : undefined),
+};
 
 /**
  * Validate and sanitize a trigger object at the payload boundary.
@@ -63,14 +76,11 @@ function validateTrigger(raw) {
     return undefined;
   }
   const trigger = { kind: raw.kind };
-  if (raw.responses !== undefined) {
-    const n = Number(raw.responses);
-    if (!Number.isFinite(n) || n < 0) return undefined;
-    trigger.responses = n;
-  }
-  if (raw.elapsed !== undefined) {
-    if (typeof raw.elapsed !== "string") return undefined;
-    trigger.elapsed = raw.elapsed;
+  for (const [field, validate] of Object.entries(TRIGGER_FIELD_VALIDATORS)) {
+    if (raw[field] === undefined) continue;
+    const clean = validate(raw[field]);
+    if (clean === undefined) return undefined;
+    trigger[field] = clean;
   }
   return trigger;
 }

package/src/dispatcher.js

@@ -3,27 +3,7 @@ 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 },
- *   });
- */
+/** Dispatch dance: resolve per-user token, register callback, ack, fire workflow, flush. */
 export class Dispatcher {
   #callbacks;
   #ack;
@@ -31,7 +11,7 @@ export class Dispatcher {
   #callbackBaseUrl;
   #workflowFile;
   #githubRepo;
-  #getGithubToken;
+  #tokenResolver;
 
   /**
    * @param {object} options
@@ -41,7 +21,7 @@ export class Dispatcher {
    * @param {string} options.callbackBaseUrl - Already normalised
    * @param {string} options.workflowFile
    * @param {string} options.githubRepo
-   * @param {() => Promise<string> | string} options.getGithubToken
+   * @param {import("./token-resolver.js").TokenResolver} options.tokenResolver
    */
   constructor({
     callbacks,
@@ -50,7 +30,7 @@ export class Dispatcher {
     callbackBaseUrl,
     workflowFile,
     githubRepo,
-    getGithubToken,
+    tokenResolver,
   }) {
     if (!callbacks) throw new Error("callbacks is required");
     if (!ack) throw new Error("ack is required");
@@ -60,31 +40,31 @@ export class Dispatcher {
     }
     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");
-    }
+    if (!tokenResolver) throw new Error("tokenResolver is required");
     this.#callbacks = callbacks;
     this.#ack = ack;
     this.#store = store;
     this.#callbackBaseUrl = callbackBaseUrl;
     this.#workflowFile = workflowFile;
     this.#githubRepo = githubRepo;
-    this.#getGithubToken = getGithubToken;
+    this.#tokenResolver = tokenResolver;
   }
 
   /**
    * @param {object} args
    * @param {object} args.ctx - Discussion context record (mutated)
    * @param {string} args.prompt
+   * @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<{token: string, correlationId: string}>}
+   * @returns {Promise<{kind: "dispatched", token: string, correlationId: string} | {kind: "link_required", authorizeUrl: string} | {kind: "reauth_required"} | {kind: "transient", error: Error}>}
    */
   async dispatch({
     ctx,
     prompt,
+    requester,
     callbackMeta,
     ackTarget,
     historyText,
@@ -92,19 +72,23 @@ export class Dispatcher {
   }) {
     if (!ctx) throw new Error("ctx is required");
     if (typeof prompt !== "string") throw new Error("prompt is required");
+    if (typeof requester !== "string") throw new Error("requester is required");
+
+    const auth = await this.#tokenResolver.resolve(ctx.channel, requester);
+    if (auth.kind !== "token") return auth;
 
     const correlationId = randomUUID();
-    const token = this.#callbacks.register(correlationId, callbackMeta ?? {});
+    const mergedMeta = { ...(callbackMeta ?? {}), requester };
+    const token = this.#callbacks.register(correlationId, mergedMeta);
     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,
+        token: auth.token,
         prompt,
         callbackUrl,
         correlationId,
@@ -117,7 +101,7 @@ export class Dispatcher {
       ctx.last_active_at = Date.now();
       await this.#store.add(ctx);
       await this.#store.flush();
-      return { token, correlationId };
+      return { kind: "dispatched", token, correlationId };
     } catch (err) {
       if (ackTarget !== undefined) await this.#ack.finish(token, ackTarget);
       this.#callbacks.consume(token);

package/src/index.js

@@ -24,6 +24,7 @@ export {
   DEFAULT_TYPING_VERBS,
 } from "./acknowledgement.js";
 export { Dispatcher } from "./dispatcher.js";
+export { TokenResolver } from "./token-resolver.js";
 export {
   CallbackHandlerError,
   createCallbackHandler,

package/src/progress-ticker.js

@@ -37,15 +37,17 @@ export class ProgressTicker {
       throw new Error("tick must be a function");
     }
     this.stop(token);
-    const timer = setInterval(async () => {
+    const safeTick = async () => {
       try {
         await tick();
       } catch {
         this.stop(token);
       }
-    }, this.#intervalMs);
+    };
+    const timer = setInterval(safeTick, this.#intervalMs);
     timer.unref?.();
     this.#timers.set(token, timer);
+    safeTick();
   }
 
   /**

package/src/resume-scheduler.js

@@ -3,46 +3,7 @@ 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();
- */
+/** Channel-agnostic suspend/resume lifecycle for the discuss-mode trace. */
 export class ResumeScheduler {
   #dispatcher;
   #store;
@@ -51,6 +12,7 @@ export class ResumeScheduler {
   #prompt;
   #buildResumeInputs;
   #buildCallbackMeta;
+  #onDeclined;
 
   /**
    * @param {object} options
@@ -60,6 +22,7 @@ export class ResumeScheduler {
    * @param {string} [options.prompt] - Default "Resume requested."
    * @param {(ctx: object) => object} [options.buildCallbackMeta]
    * @param {(ctx: object) => object} [options.buildResumeInputs]
+   * @param {((ctx: object, outcome: object) => Promise<void>) | null} [options.onDeclined]
    */
   constructor({
     dispatcher,
@@ -68,6 +31,7 @@ export class ResumeScheduler {
     prompt = DEFAULT_PROMPT,
     buildCallbackMeta = (ctx) => ({ discussionId: ctx.discussion_id }),
     buildResumeInputs = () => ({}),
+    onDeclined = null,
   }) {
     if (!dispatcher) throw new Error("dispatcher is required");
     if (!store) throw new Error("store is required");
@@ -77,12 +41,16 @@ export class ResumeScheduler {
     if (typeof buildResumeInputs !== "function") {
       throw new Error("buildResumeInputs must be a function");
     }
+    if (onDeclined != null && typeof onDeclined !== "function") {
+      throw new Error("onDeclined must be a function");
+    }
     this.#dispatcher = dispatcher;
     this.#store = store;
     this.#logger = logger ?? null;
     this.#prompt = prompt;
     this.#buildCallbackMeta = buildCallbackMeta;
     this.#buildResumeInputs = buildResumeInputs;
+    this.#onDeclined = onDeclined;
     this.#elapsed = new ElapsedScheduler({
       onFire: (cid) => this.#fireElapsed(cid),
       onError: (err, cid) =>
@@ -99,10 +67,9 @@ export class ResumeScheduler {
 
   /**
    * 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.
+   * trigger, the history index at recess time, and the triggering
+   * requester onto `ctx.open_rfcs[correlationId]`. If the trigger has an
+   * elapsed component, schedules an in-memory timer.
    *
    * The caller is responsible for flushing the store after this call —
    * `enterRecess` mutates ctx but does not write.
@@ -110,28 +77,27 @@ export class ResumeScheduler {
    * @param {object} ctx
    * @param {string} correlationId
    * @param {import("./triggers.js").ResumeTrigger} trigger
+   * @param {string} requester - Surface user id of the triggering human
    */
-  enterRecess(ctx, correlationId, trigger) {
+  enterRecess(ctx, correlationId, trigger, requester) {
     if (!trigger) return;
     const openedAt = Date.now();
     ctx.open_rfcs[correlationId] = {
       trigger,
       opened_at: openedAt,
       history_index_at_open: ctx.history.length,
+      requester,
     };
-    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);
-      }
+    if (trigger.kind === "elapsed" && 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.
+   * and cancels any associated elapsed timer. Idempotent.
    *
    * @param {object} ctx
    * @param {string} correlationId
@@ -142,29 +108,21 @@ export class ResumeScheduler {
   }
 
   /**
-   * 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.
+   * Walk `ctx.open_rfcs`. For each rfc whose trigger has fired,
+   * redispatch the workflow. Returns a summary so the host can decide
+   * whether to additionally fire a fresh lead session.
    *
    * @param {object} ctx
-   * @returns {Promise<{
-   *   fired: number,
-   *   hasOpenRfc: boolean,
-   *   freshDispatchAllowed: boolean,
-   * }>}
+   * @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 result = await this.#redispatch(ctx, correlationId, historySince);
+      if (result.kind === "dispatched") {
+        this.cancelRecess(ctx, correlationId);
+      }
     }
     const hasOpenRfc = Object.keys(ctx.open_rfcs ?? {}).length > 0;
     return {
@@ -175,9 +133,7 @@ export class ResumeScheduler {
   }
 
   /**
-   * Rehydrate persistent elapsed timers from the store. Call once after
-   * the bridge server starts so deadlines set before a restart still
-   * fire.
+   * Rehydrate persistent elapsed timers from the store.
    * @returns {Promise<void>}
    */
   async rearm() {
@@ -204,7 +160,7 @@ export class ResumeScheduler {
       const trigger = rfc.trigger;
       if (!trigger) continue;
       const observed = {
-        responses: ctx.history.length - rfc.history_index_at_open,
+        replies: ctx.history.length - rfc.history_index_at_open,
         opened_at: rfc.opened_at,
       };
       if (evaluateTrigger(trigger, observed, Date.now()).fired) {
@@ -215,19 +171,38 @@ export class ResumeScheduler {
   }
 
   async #redispatch(ctx, correlationId, historySince) {
+    const rfc = ctx.open_rfcs[correlationId];
+    if (!rfc.requester) {
+      this.cancelRecess(ctx, correlationId);
+      this.#logger?.info?.("resume.skip", "rfc missing requester", {
+        correlation_id: correlationId,
+      });
+      return {
+        kind: "transient",
+        error: new Error("rfc missing requester"),
+      };
+    }
     const resumeContext = JSON.stringify({
       correlation_id: correlationId,
       history_since: historySince,
     });
-    await this.#dispatcher.dispatch({
+    const result = await this.#dispatcher.dispatch({
       ctx,
       prompt: this.#prompt,
+      requester: rfc.requester,
       callbackMeta: this.#buildCallbackMeta(ctx),
       workflowInputs: {
         ...this.#buildResumeInputs(ctx),
         resumeContext,
       },
     });
+    if (result.kind !== "dispatched") {
+      this.cancelRecess(ctx, correlationId);
+      await this.#store.add(ctx);
+      await this.#store.flush();
+      if (this.#onDeclined) await this.#onDeclined(ctx, result);
+    }
+    return result;
   }
 
   async #fireElapsed(correlationId) {
@@ -235,11 +210,13 @@ export class ResumeScheduler {
     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();
+    const result = await this.#redispatch(ctx, correlationId, historySince);
+    if (result.kind === "dispatched") {
+      this.cancelRecess(ctx, correlationId);
+      ctx.last_active_at = Date.now();
+      await this.#store.add(ctx);
+      await this.#store.flush();
+    }
   }
 
   async #findContextWithRfc(correlationId) {

package/src/token-resolver.js

@@ -0,0 +1,41 @@
+import { ghauth } from "@forwardimpact/libtype";
+
+/** Maps ghauth GetToken oneof + gRPC transport into a discriminated DispatchAuth result. */
+export class TokenResolver {
+  #client;
+
+  /** @param {object} client - ghauth gRPC client */
+  constructor(client) {
+    if (!client) throw new Error("ghauth client is required");
+    this.#client = client;
+  }
+
+  /** @returns {Promise<{kind: string, token?: string, authorizeUrl?: string, error?: Error}>} */
+  async resolve(surface, surfaceUserId) {
+    try {
+      const req = new ghauth.GetTokenRequest({
+        surface,
+        surface_user_id: surfaceUserId,
+      });
+      const res = await this.#client.GetToken(req);
+      switch (res.result) {
+        case "token":
+          return { kind: "token", token: res.token };
+        case "link_required":
+          return {
+            kind: "link_required",
+            authorizeUrl: res.link_required.authorize_url,
+          };
+        case "re_auth_required":
+          return { kind: "reauth_required" };
+        default:
+          return {
+            kind: "transient",
+            error: new Error("unexpected GetToken result"),
+          };
+      }
+    } catch (err) {
+      return { kind: "transient", error: err };
+    }
+  }
+}

package/src/triggers.js

@@ -1,10 +1,13 @@
 /**
  * @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"`.
+ * @property {"missing_input"|"escalation_needed"|"elapsed"} kind
+ * @property {number} [replies] - Required for `kind: "missing_input"`.
+ *   Number of new replies on the dispatching thread needed to fire.
+ * @property {string} [elapsed] - Required for `kind: "elapsed"`.
+ *   ISO-8601 duration, e.g. `"P14D"`, `"PT12H"`, `"P1DT6H"`.
+ * @property {string} [signal] - Required for `kind: "escalation_needed"`.
+ *   Reserved for future use. The bridge throws when evaluating this kind
+ *   until signal-based resume support lands.
  */
 
 const ISO_8601_DURATION =
@@ -42,7 +45,7 @@ export function parseIsoDuration(duration) {
  * Evaluate whether a resume trigger has fired.
  *
  * @param {ResumeTrigger} trigger
- * @param {{responses?: number, opened_at?: number}} observed
+ * @param {{replies?: number, opened_at?: number}} observed
  * @param {number} now - ms epoch (caller-provided for testability)
  * @returns {{fired: boolean, due_at?: number}}
  */
@@ -56,37 +59,27 @@ export function evaluateTrigger(trigger, observed, now) {
   observed ??= {};
 
   switch (trigger.kind) {
-    case "responses":
-      return evaluateResponses(trigger, observed);
+    case "missing_input":
+      return evaluateMissingInput(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 };
-    }
+    case "escalation_needed":
+      throw new Error(
+        "escalation_needed is reserved for future use. See the follow-up spec for signal-based resume.",
+      );
     default:
       throw new Error(`Unsupported trigger kind: ${trigger.kind}`);
   }
 }
 
-function evaluateResponses(trigger, observed) {
-  if (typeof trigger.responses !== "number" || trigger.responses < 1) {
+function evaluateMissingInput(trigger, observed) {
+  if (typeof trigger.replies !== "number" || trigger.replies < 1) {
     throw new Error(
-      'trigger.responses must be a positive number for kind "responses"',
+      'trigger.replies must be a positive number for kind "missing_input"',
     );
   }
-  const seen = observed.responses ?? 0;
-  return { fired: seen >= trigger.responses };
+  const seen = observed.replies ?? 0;
+  return { fired: seen >= trigger.replies };
 }
 
 function evaluateElapsed(trigger, observed, now) {