@opengeni/api-router 0.30.1 → 1.0.0

package/src/integrations/slack-mrkdwn.ts

@@ -0,0 +1,193 @@
+/**
+ * Markdown to Slack mrkdwn for model-authored text OpenGeni posts to Slack.
+ *
+ * Agents write ordinary Markdown because the same reply renders as Markdown in
+ * the OpenGeni console. Slack message text does not render Markdown headings,
+ * `**bold**`, or `[label](url)` links, so a reply that reads well in the
+ * console arrives in Slack full of literal syntax. This rewrites only that
+ * syntax, only for the bytes handed to Slack: stored session events, model
+ * history, and every other surface keep the model's exact text. It is
+ * formatting at a third-party sink, not content classification or redaction.
+ *
+ * Code is never rewritten: fenced code blocks keep every line between their
+ * fences, and inline code spans are copied as they are.
+ *
+ * The output is part of the Slack post and update ledgers' request digest, so a
+ * change to it changes the bytes an in-flight operation is bound to. Delivery
+ * (`deliverSlackModelText` in `slack-interactions.ts`) falls back only to the
+ * unformatted text; a later output change must keep the previous rendering
+ * reachable the same way, or operations started before the deploy conflict on
+ * every retry.
+ */
+
+/**
+ * A private provider citation handle: U+E200 `cite`, one or more U+E202
+ * separated references, then U+E201. Codex web search can emit these without
+ * the annotation table that would make them resolvable, so they carry nothing a
+ * Slack reader can use. The OpenGeni timeline hides the same handles
+ * (`stripOpaqueCitationTokens` in `packages/react/src/timeline/projection.ts`).
+ */
+const PROVIDER_CITATION_TOKEN =
+  /[ \t]*\u{E200}(?:cite|filecite)(?:\u{E202}[^\u{E200}-\u{E202}]*)*\u{E201}/gu;
+/** Stray citation delimiters, for example from a token cut short upstream. */
+const PROVIDER_CITATION_DELIMITER = /[\u{E200}-\u{E202}]/gu;
+
+/**
+ * A fence at any indentation. Agents nest code under list items (a `10.` item
+ * or a nested bullet puts the fence four or more spaces in), and Slack has no
+ * indented code block, so a fence line is a fence wherever it starts.
+ */
+const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})(.*)$/u;
+const ATX_HEADING = /^ {0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/u;
+const BULLET = /^([ \t]*)[-*+][ \t]+(?=\S)/u;
+const THEMATIC_BREAK = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/u;
+
+/**
+ * Spans that must reach Slack exactly as written and are set aside before any
+ * link is read: inline code, and Slack's own `<...>` tokens (mentions, channel
+ * links, and links already in Slack form).
+ */
+const CODE_SPAN_OR_SLACK_TOKEN =
+  /(`+)(?!`)[^\n]*?(?<!`)\1(?!`)|<(?:[@#!]|https?:|mailto:)[^<>\n]*>/gu;
+
+/**
+ * A Markdown link or image whose target is a web or mail address. Other
+ * targets, such as OpenGeni's own `artifact:` and `sandbox:` links, mean
+ * nothing in Slack and are left as written rather than turned into dead links.
+ * One level of balanced parentheses is allowed in the URL (as in Wikipedia
+ * links), and an optional link title is dropped.
+ */
+const MARKDOWN_LINK =
+  /!?\[((?:[^[\]\n]|\[[^[\]\n]*\])+)\]\(\s*((?:https?:\/\/|mailto:)(?:[^\s()<>|]|\([^\s()<>|]*\))+)(?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^()\n]*\)))?\s*\)/gu;
+
+/** Bare URLs are set aside after links: they may legitimately contain `__` or `**`. */
+const BARE_URL = /\bhttps?:\/\/[^\s<>]+/gu;
+
+const BOLD_ITALIC_ASTERISK = /\*\*\*(?=[^\s*])((?:[^*\n]|\*(?!\*))+?)(?<=[^\s*])\*\*\*/gu;
+const BOLD_ASTERISK = /\*\*(?=[^\s*])((?:[^*\n]|\*(?!\*))+?)(?<=[^\s*])\*\*/gu;
+const BOLD_UNDERSCORE =
+  /(?<![\p{L}\p{N}_])__(?=[^\s_])((?:[^_\n]|_(?!_))+?)(?<=[^\s_])__(?![\p{L}\p{N}_])/gu;
+const STRIKETHROUGH = /~~(?=[^\s~])((?:[^~\n]|~(?!~))+?)(?<=[^\s~])~~/gu;
+const PLACEHOLDER = /\u0000(\d+)\u0000/gu;
+
+/** Remove provider citation handles and any stray citation delimiters. */
+export function stripProviderCitationMarkers(text: string): string {
+  return text.replace(PROVIDER_CITATION_TOKEN, "").replace(PROVIDER_CITATION_DELIMITER, "");
+}
+
+/**
+ * Rewrite common Markdown as Slack mrkdwn.
+ *
+ * - `# Heading` (any level) becomes a bold line.
+ * - `**bold**` and `__bold__` become `*bold*`, `***both***` becomes `*_both_*`,
+ *   and `~~struck~~` becomes `~struck~`.
+ * - `[label](https://...)` becomes `<https://...|label>`.
+ * - `-`, `*`, and `+` bullets become Slack's `•` bullet, keeping indentation;
+ *   numbered lists and block quotes are already Slack syntax and stay as they are.
+ * - Fenced code blocks, at any indentation, keep their contents byte for byte.
+ *   The opening fence loses its language tag, which Slack would otherwise print
+ *   as the first code line, and an unclosed block is closed so Slack still
+ *   renders it as code.
+ * - Provider citation handles are removed.
+ *
+ * Text that uses none of this syntax comes back unchanged.
+ */
+export function slackMrkdwnFromMarkdown(markdown: string): string {
+  const lines = stripProviderCitationMarkers(markdown).split("\n");
+  const output: string[] = [];
+  let fence: { character: string; length: number } | null = null;
+  for (const line of lines) {
+    if (fence) {
+      if (closesFence(line, fence)) {
+        output.push("```");
+        fence = null;
+      } else {
+        output.push(line);
+      }
+      continue;
+    }
+    const opening = FENCE_OPEN.exec(line);
+    // A backtick fence's info string cannot contain a backtick; such a line is
+    // inline code, not a fence.
+    if (opening && !(opening[1]!.startsWith("`") && opening[2]!.includes("`"))) {
+      fence = { character: opening[1]![0]!, length: opening[1]!.length };
+      output.push("```");
+      continue;
+    }
+    output.push(slackLine(line));
+  }
+  if (fence) output.push("```");
+  return output.join("\n");
+}
+
+function closesFence(line: string, fence: { character: string; length: number }): boolean {
+  const trimmed = line.trim();
+  return (
+    trimmed.length >= fence.length &&
+    [...trimmed].every((character) => character === fence.character)
+  );
+}
+
+function slackLine(line: string): string {
+  if (THEMATIC_BREAK.test(line)) return line;
+  const heading = ATX_HEADING.exec(line);
+  if (heading) {
+    const content = slackInline(heading[1]!, { heading: true }).trim();
+    return content ? `*${content}*` : line;
+  }
+  const bullet = BULLET.exec(line);
+  if (bullet) {
+    return `${bullet[1]}• ${slackInline(line.slice(bullet[0].length), { heading: false })}`;
+  }
+  return slackInline(line, { heading: false });
+}
+
+function slackInline(text: string, options: { heading: boolean }): string {
+  const kept: string[] = [];
+  const keep = (value: string) => {
+    kept.push(value);
+    return `\u0000${kept.length - 1}\u0000`;
+  };
+  // The placeholders are NUL-delimited, so a NUL in the model text itself
+  // could collide with one. Slack does not render NUL; drop it.
+  let working = text.replace(/\u0000/gu, "");
+  working = working.replace(CODE_SPAN_OR_SLACK_TOKEN, keep);
+  working = working.replace(MARKDOWN_LINK, (_match, label: string, url: string) =>
+    keep(slackLink(restore(label, kept), url)),
+  );
+  working = working.replace(BARE_URL, keep);
+  if (options.heading) {
+    // The whole heading becomes one bold span, so emphasis inside it would
+    // nest and break Slack's parser. Drop the emphasis markers instead.
+    working = working
+      .replace(BOLD_ASTERISK, "$1")
+      .replace(BOLD_UNDERSCORE, "$1")
+      .replace(/\*/gu, "");
+  } else {
+    working = working
+      .replace(BOLD_ITALIC_ASTERISK, "*_$1_*")
+      .replace(BOLD_ASTERISK, "*$1*")
+      .replace(BOLD_UNDERSCORE, "*$1*");
+  }
+  working = working.replace(STRIKETHROUGH, "~$1~");
+  return restore(working, kept);
+}
+
+function restore(text: string, kept: readonly string[]): string {
+  return text.replace(PLACEHOLDER, (_match, index: string) => kept[Number(index)] ?? "");
+}
+
+function slackLink(label: string, url: string): string {
+  const text = label
+    .replace(BOLD_ASTERISK, "$1")
+    .replace(BOLD_UNDERSCORE, "$1")
+    .replace(/`/gu, "")
+    .trim();
+  if (!text || text === url) return `<${url}>`;
+  return `<${url}|${escapeSlackLinkLabel(text)}>`;
+}
+
+/** Slack reads `&`, `<`, and `>` as control characters inside a link. */
+function escapeSlackLinkLabel(label: string): string {
+  return label.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+}

package/src/integrations/slack-routing.ts

@@ -0,0 +1,337 @@
+/**
+ * Per-channel and per-DM Slack workspace routing.
+ *
+ * Routing is decided BEFORE any agent runs, from durable facts only, so it can
+ * never be a model judgement. The resolver is pure with respect to the database
+ * reads it is handed: it returns a decision, and the caller persists and acts on
+ * it.
+ *
+ * Two rules are load-bearing and easy to break by accident:
+ *
+ *   A mapped thread keeps the workspace it was created in, unconditionally,
+ *   including after the channel has been re-pointed. Otherwise a live
+ *   conversation would silently change tenants mid-thread.
+ *
+ *   A subject who lacks access to the routed workspace is NEVER quietly served
+ *   from another workspace they happen to belong to. Every failure is explicit
+ *   and creates no session.
+ */
+import type { AccessGrant } from "@opengeni/contracts";
+import type {
+  SlackChannelRoute,
+  SlackInteractionInboxEntry,
+  SlackRoutableWorkspace,
+  SlackUserDmRoute,
+} from "@opengeni/db";
+
+export type SlackRouteTenancy = { accountId: string; workspaceId: string };
+
+export type SlackRouteResolution =
+  | (SlackRouteTenancy & {
+      kind: "resolved";
+      label: string | null;
+      source:
+        | "thread"
+        | "prefix"
+        | "channel"
+        | "dm_route"
+        | "dm_personal"
+        | "sole_candidate"
+        | "installation";
+    })
+  | { kind: "ask"; candidates: readonly SlackRoutableWorkspace[] }
+  | {
+      kind: "denied";
+      reason: "no_access_to_named" | "no_access_to_route" | "no_candidates";
+      requested: string | null;
+      candidates: readonly SlackRoutableWorkspace[];
+    };
+
+/**
+ * A Slack direct message to the bot, by any trigger that can carry one.
+ *
+ * `isDirectMessageShortcut` is deliberately narrower: it means "a message
+ * shortcut invoked inside a DM", which is a private-handoff concern. Routing
+ * cares about the broader question of whether this conversation is one human's
+ * private channel with the bot, which is also true of an ordinary `dm` event.
+ */
+export function isSlackDirectMessageConversation(
+  entry: Pick<SlackInteractionInboxEntry, "triggerKind" | "slackChannelId">,
+): boolean {
+  return entry.triggerKind === "dm" || entry.slackChannelId.startsWith("D");
+}
+
+const PREFIX = "in ";
+
+/**
+ * Trigger kinds whose text the invoking human wrote themselves. A message
+ * shortcut and a reaction both act on another person's message.
+ */
+const AUTHORED_BY_INVOKER: ReadonlySet<string> = new Set([
+  "app_mention",
+  "dm",
+  "slash_command",
+  "thread_reply",
+]);
+
+/**
+ * Split a leading bot mention off the message text.
+ *
+ * Slack delivers an `app_mention` with the mention still in the text
+ * (`<@U123> do the thing`), and OpenGeni stores it verbatim. The workspace
+ * prefix is only an override when it is the first thing the person typed, so it
+ * is parsed after the mention rather than at byte 0 of the raw text. Everything
+ * split off here is put back, so the message the model sees is unchanged apart
+ * from the addressing the person used to route it.
+ */
+export function splitSlackLeadingMention(
+  text: string,
+  botUserId: string | null,
+): { lead: string; rest: string } {
+  if (!botUserId || !/^[UWB][A-Z0-9]{1,63}$/u.test(botUserId)) return { lead: "", rest: text };
+  const mention = `<@${botUserId}>`;
+  if (!text.startsWith(mention)) return { lead: "", rest: text };
+  const remainder = text.slice(mention.length);
+  const trimmed = remainder.replace(/^[ \t]+/u, "");
+  return { lead: text.slice(0, text.length - trimmed.length), rest: trimmed };
+}
+
+/**
+ * The strict `in <workspace>: ...` override.
+ *
+ * Parsed only at byte 0, so ordinary prose that happens to contain the word
+ * cannot trigger it, and matched case-insensitively against the exact label of a
+ * workspace the subject can already start work in. A prefix that names nothing
+ * recognizable is NOT a suggestion that falls through: it is a refusal, because
+ * silently ignoring an explicit override is how a message lands somewhere the
+ * person did not intend.
+ */
+export function parseSlackWorkspacePrefix(text: string): {
+  requested: string;
+  remainder: string;
+} | null {
+  if (!text.toLowerCase().startsWith(PREFIX)) return null;
+  const separator = text.indexOf(":");
+  if (separator <= PREFIX.length) return null;
+  const requested = text.slice(PREFIX.length, separator).trim();
+  if (requested.length === 0) return null;
+  // A bare address with nothing after it is not a request.
+  if (text.slice(separator + 1).trim().length === 0) return null;
+  // A label is one line. A colon further down a multi-line message is not a
+  // prefix, it is punctuation.
+  if (/[\r\n]/u.test(requested)) return null;
+  return { requested, remainder: text.slice(separator + 1).replace(/^[ \t]+/u, "") };
+}
+
+function matchCandidate(
+  candidates: readonly SlackRoutableWorkspace[],
+  requested: string,
+): SlackRoutableWorkspace | null | "ambiguous" {
+  const wanted = requested.toLowerCase();
+  const matches = candidates.filter((candidate) => candidate.label.toLowerCase() === wanted);
+  // Two workspaces whose labels differ only by case are not a tie to break
+  // silently: guessing one is the same failure as ignoring the override.
+  if (matches.length > 1) return "ambiguous";
+  return matches[0] ?? null;
+}
+
+export type SlackRouteInputs = {
+  /** The installation binding's tenancy. Always the fallback, never a silent one. */
+  home: SlackRouteTenancy;
+  entry: Pick<
+    SlackInteractionInboxEntry,
+    "triggerKind" | "slackChannelId" | "slackUserId" | "text"
+  >;
+  /**
+   * The tenancy of an interaction already mapped to this thread, if any. A
+   * mapped thread wins unconditionally.
+   */
+  threadTenancy: SlackRouteTenancy | null;
+  channelRoute: SlackChannelRoute | null;
+  dmRoute: SlackUserDmRoute | null;
+  /** The subject's own personal workspace in the home organization, if any. */
+  personalWorkspaceId: string | null;
+  /** Workspaces this subject may actually start work in, ordered stably. */
+  candidates: readonly SlackRoutableWorkspace[];
+  /** The installation's bot user, so a mention does not hide the prefix. */
+  botUserId: string | null;
+  /** `OPENGENI_SLACK_WORKSPACE_ROUTING_ENABLED`. */
+  routingEnabled: boolean;
+  /** Whether the first-use picker exists yet. Until it does, ambiguity keeps home. */
+  askEnabled: boolean;
+};
+
+function labelFor(
+  candidates: readonly SlackRoutableWorkspace[],
+  workspaceId: string,
+): string | null {
+  return candidates.find((candidate) => candidate.workspaceId === workspaceId)?.label ?? null;
+}
+
+/**
+ * Decide which workspace this Slack message starts work in.
+ *
+ * First match wins, and the order is deliberate: continuity beats an explicit
+ * override beats configuration beats derivation beats asking.
+ */
+export function resolveSlackWorkspaceRoute(input: SlackRouteInputs): SlackRouteResolution {
+  // A personal workspace is only ever a destination for that person's own bot
+  // DM. Offering it in a channel would be wrong twice over: routing a shared
+  // conversation into one member's private space hides it from everyone else
+  // in the channel, and - because managed tenancy provisions a personal
+  // workspace for every member - counting it as a candidate means nobody ever
+  // has exactly one. That defeats the sole-candidate rule below, so an
+  // organization with a single shared workspace would be asked to choose in
+  // every channel despite having no choice to make.
+  const directMessage = isSlackDirectMessageConversation(input.entry);
+  const candidates = directMessage
+    ? input.candidates
+    : input.candidates.filter((candidate) => !candidate.personal);
+
+  const installation = {
+    kind: "resolved" as const,
+    accountId: input.home.accountId,
+    workspaceId: input.home.workspaceId,
+    label: labelFor(candidates, input.home.workspaceId),
+    source: "installation" as const,
+  };
+
+  // 0. With routing off no routing read is consulted, so an existing install is
+  //    byte-identical. A thread that a previous flag-on window already mapped is
+  //    still honoured, because its interaction, session and events genuinely
+  //    live there: turning the flag off must stop new routing, not strand a
+  //    conversation by addressing it in a workspace it is not in.
+  if (!input.routingEnabled) {
+    return input.threadTenancy
+      ? {
+          kind: "resolved",
+          accountId: input.threadTenancy.accountId,
+          workspaceId: input.threadTenancy.workspaceId,
+          label: null,
+          source: "thread",
+        }
+      : installation;
+  }
+
+  // 1. A mapped thread keeps its workspace, even if the channel moved since.
+  if (input.threadTenancy) {
+    return {
+      kind: "resolved",
+      accountId: input.threadTenancy.accountId,
+      workspaceId: input.threadTenancy.workspaceId,
+      label: labelFor(candidates, input.threadTenancy.workspaceId),
+      source: "thread",
+    };
+  }
+
+  // 2. The strict prefix override. It applies to this message only and never
+  //    writes a route row: an override is not a decision about the channel.
+  //
+  //    Only text the invoking human actually typed can address anything. A
+  //    message shortcut and a reaction both carry SOMEONE ELSE'S message, so a
+  //    prefix found there was never an instruction to OpenGeni.
+  const prefix = AUTHORED_BY_INVOKER.has(input.entry.triggerKind)
+    ? parseSlackWorkspacePrefix(splitSlackLeadingMention(input.entry.text, input.botUserId).rest)
+    : null;
+  if (prefix) {
+    const named = matchCandidate(candidates, prefix.requested);
+    if (named === "ambiguous" || !named) {
+      return {
+        kind: "denied",
+        reason: "no_access_to_named",
+        requested: prefix.requested,
+        candidates: candidates,
+      };
+    }
+    return {
+      kind: "resolved",
+      accountId: named.accountId,
+      workspaceId: named.workspaceId,
+      label: named.label,
+      source: "prefix",
+    };
+  }
+
+  // 3. The channel's remembered answer.
+  if (input.channelRoute) {
+    return {
+      kind: "resolved",
+      accountId: input.channelRoute.targetAccountId,
+      workspaceId: input.channelRoute.targetWorkspaceId,
+      label: labelFor(candidates, input.channelRoute.targetWorkspaceId),
+      source: "channel",
+    };
+  }
+
+  // 4. A direct message is this human's own conversation with the bot, so it
+  //    lands in their own workspace unless they chose otherwise. The personal
+  //    workspace id is DERIVED from an active organization membership pointer;
+  //    it is never accepted from a Slack payload or a route row.
+  if (directMessage) {
+    if (input.dmRoute) {
+      return {
+        kind: "resolved",
+        accountId: input.dmRoute.targetAccountId,
+        workspaceId: input.dmRoute.targetWorkspaceId,
+        label: labelFor(candidates, input.dmRoute.targetWorkspaceId),
+        source: "dm_route",
+      };
+    }
+    if (input.personalWorkspaceId) {
+      return {
+        kind: "resolved",
+        accountId: input.home.accountId,
+        workspaceId: input.personalWorkspaceId,
+        label: labelFor(candidates, input.personalWorkspaceId),
+        source: "dm_personal",
+      };
+    }
+    // No workspace of their own is not the same as no workspace at all. Fall
+    // through to the ordinary rules so a member of exactly one shared workspace
+    // can still work in their bot DM.
+  }
+
+  // 5. One workspace is not a choice. This is what keeps the flag quiet for
+  //    installs that only ever had one workspace.
+  const sole = candidates[0];
+  if (candidates.length === 1 && sole) {
+    return {
+      kind: "resolved",
+      accountId: sole.accountId,
+      workspaceId: sole.workspaceId,
+      label: sole.label,
+      source: "sole_candidate",
+    };
+  }
+
+  if (candidates.length === 0) {
+    return { kind: "denied", reason: "no_candidates", requested: null, candidates: [] };
+  }
+
+  // 6. Genuinely ambiguous. Until the picker exists, keep the installation's
+  //    workspace rather than inventing an answer.
+  return input.askEnabled ? { kind: "ask", candidates: candidates } : installation;
+}
+
+/**
+ * The message text the model actually sees.
+ *
+ * A prefix override is addressing information, not part of the request, so it is
+ * stripped exactly once and only when it matched.
+ */
+export function slackRoutedRequestText(
+  text: string,
+  resolution: SlackRouteResolution,
+  botUserId: string | null,
+): string {
+  if (resolution.kind !== "resolved" || resolution.source !== "prefix") return text;
+  const { lead, rest } = splitSlackLeadingMention(text, botUserId);
+  // Reached only for a `prefix` resolution, which the authorship rule above
+  // already restricted to text the invoking human wrote.
+  const parsed = parseSlackWorkspacePrefix(rest);
+  return parsed ? `${lead}${parsed.remainder}` : text;
+}
+
+export type SlackRouteAuthorization =
+  | { kind: "authorized"; grant: AccessGrant; tenancy: SlackRouteTenancy; label: string | null }
+  | { kind: "denied"; reason: "no_access_to_route"; tenancy: SlackRouteTenancy };