@opengeni/api-router 3.0.1 → 3.1.2

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

@@ -78,7 +78,7 @@ const AUTHORED_BY_INVOKER: ReadonlySet<string> = new Set([
  * 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
+ * (`<@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
@@ -229,7 +229,7 @@ export function resolveSlackWorkspaceRoute(input: SlackRouteInputs): SlackRouteR
   //
   //    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.
+  //    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;

package/src/integrations/slack-session-defaults.ts

@@ -0,0 +1,224 @@
+import {
+  resourceMountPath,
+  resourceMountPathCollisionKey,
+  type AccessGrant,
+  type GitHubRepository,
+  type RepositoryResourceRef,
+} from "@opengeni/contracts";
+import { listRecentSessionRepositoryResources } from "@opengeni/db";
+import { hasPermission, type ApiRouteDeps } from "@opengeni/core";
+import { githubRepositoryResourceRef, listWorkspaceGitHubRepositories } from "../github-access";
+
+/**
+ * A Slack task starts with at most this many repositories. Each one is a
+ * shallow, blob-filtered fetch before the first command, so the set stays
+ * small: the person's own most recently used repositories, not a catalog.
+ */
+export const SLACK_SESSION_RECENT_REPOSITORY_LIMIT = 5;
+
+/** How far back the person's own sessions count as recent use. */
+export const SLACK_SESSION_RECENT_REPOSITORY_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+function githubUriKey(uri: string): string | null {
+  try {
+    const url = new URL(uri);
+    const path = url.pathname
+      .replace(/^\/+|\/+$/gu, "")
+      .replace(/\.git$/iu, "")
+      .toLowerCase();
+    return path ? `${url.host.toLowerCase()}/${path}` : null;
+  } catch {
+    return null;
+  }
+}
+
+function positiveRepositoryId(value: unknown): number | null {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return value;
+  if (typeof value === "string" && /^[1-9]\d{0,15}$/u.test(value)) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+/**
+ * Pick a Slack task's repositories: the person's recently used repositories,
+ * in recency order, that the workspace GitHub App catalog still offers them.
+ *
+ * `recent` is a usage signal only, and only repositories the person attached
+ * themselves count: an automatically attached (`optional`) one never does. A
+ * repository reaches the task only through its current catalog entry (the
+ * same catalog and `github:use` permission as the website picker), on its
+ * default branch, so a Slack task never reaches a repository the person could
+ * not attach on the website today. Archived and
+ * empty repositories are skipped when GitHub reported that, because a clone of
+ * an empty repository has nothing to check out. Every returned resource is
+ * best effort (`optional`): one failed clone warns instead of failing setup.
+ */
+export function selectRecentRepositoryResources(
+  recent: readonly RepositoryResourceRef[],
+  catalog: readonly GitHubRepository[],
+  limit = SLACK_SESSION_RECENT_REPOSITORY_LIMIT,
+): RepositoryResourceRef[] {
+  const byId = new Map<number, GitHubRepository[]>();
+  const byUri = new Map<string, GitHubRepository>();
+  const ordered = [...catalog].sort(
+    (left, right) => left.installationId - right.installationId || left.id - right.id,
+  );
+  for (const repository of ordered) {
+    byId.set(repository.id, [...(byId.get(repository.id) ?? []), repository]);
+    const key = githubUriKey(repository.cloneUrl);
+    if (key && !byUri.has(key)) byUri.set(key, repository);
+  }
+  const chosen = new Set<string>();
+  const mountKeys = new Set<string>();
+  const resources: RepositoryResourceRef[] = [];
+  for (const used of recent) {
+    if (resources.length >= limit) break;
+    // A repository Opengeni attached automatically is not a choice the person
+    // made; counting it would keep re-attaching it to every later Slack task.
+    if (used.optional === true) continue;
+    const repositoryId = positiveRepositoryId(
+      used.githubRepositoryId ?? (used.provider === "github" ? used.repositoryId : undefined),
+    );
+    const installationId = positiveRepositoryId(
+      used.githubInstallationId ?? (used.provider === "github" ? used.installationId : undefined),
+    );
+    const candidates = repositoryId !== null ? (byId.get(repositoryId) ?? []) : [];
+    const uriKey = githubUriKey(used.uri);
+    const match =
+      candidates.find((candidate) => candidate.installationId === installationId) ??
+      candidates[0] ??
+      (uriKey ? byUri.get(uriKey) : undefined);
+    if (!match) continue;
+    const identity = `${match.installationId}:${match.id}`;
+    if (chosen.has(identity)) continue;
+    chosen.add(identity);
+    if (match.archived === true || match.sizeKb === 0) continue;
+    let resource: RepositoryResourceRef;
+    try {
+      resource = { ...githubRepositoryResourceRef(match), optional: true };
+    } catch {
+      // A malformed provider URL is one unusable repository, not a failed task.
+      continue;
+    }
+    const mountKey = resourceMountPathCollisionKey(resourceMountPath(resource));
+    if (mountKeys.has(mountKey)) continue;
+    mountKeys.add(mountKey);
+    resources.push(resource);
+  }
+  return resources;
+}
+
+/**
+ * The repositories a new Slack task starts with: the person's own recently
+ * used repositories in this workspace (their own top-level sessions active in
+ * the last 30 days, most recent first, at most five), limited to what the
+ * workspace GitHub App catalog offers them now. None when they have none; the
+ * agent can still find and clone repositories through its GitHub tools.
+ *
+ * GitHub is asked only when there is something to look up. A GitHub outage or
+ * an unconfigured App starts the task without repositories instead of failing
+ * it, with a log line for diagnosis.
+ */
+export async function slackRecentRepositoryResources(
+  deps: ApiRouteDeps,
+  grant: Pick<AccessGrant, "permissions" | "subjectId">,
+  workspaceId: string,
+  now: Date = new Date(),
+): Promise<RepositoryResourceRef[]> {
+  if (!hasPermission(grant.permissions, "github:use")) return [];
+  const recent = await listRecentSessionRepositoryResources(deps.db, {
+    workspaceId,
+    subjectId: grant.subjectId,
+    since: new Date(now.getTime() - SLACK_SESSION_RECENT_REPOSITORY_WINDOW_MS),
+  });
+  if (!recent.some((resource) => resource.optional !== true)) return [];
+  let catalog: GitHubRepository[];
+  try {
+    catalog = await listWorkspaceGitHubRepositories(deps, workspaceId);
+  } catch (error) {
+    console.error("[slack-interactions] workspace repositories unavailable", {
+      workspaceId,
+      errorCode: (error instanceof Error ? error.name : "unknown")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]/gu, "_")
+        .slice(0, 128),
+    });
+    return [];
+  }
+  return selectRecentRepositoryResources(recent, catalog);
+}
+
+const OPEN_GENI_LINK_PATTERN =
+  /https?:\/\/([^\s/<>|?#]+)(\/workspaces\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?:\/sessions\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?)/giu;
+
+const MAX_OTHER_DEPLOYMENT_LINKS = 5;
+
+export type OtherDeploymentLink = { url: string; host: string };
+
+function siteOf(hostname: string): string | null {
+  if (/^[\d.]+$/u.test(hostname) || hostname.includes(":")) return null;
+  const labels = hostname.split(".").filter(Boolean);
+  return labels.length >= 2 ? labels.slice(-2).join(".") : null;
+}
+
+/**
+ * Opengeni workspace or session links in `text` that point at a sibling
+ * deployment of this one (for example staging versus production).
+ *
+ * A sibling is a different host under the same parent domain as this
+ * deployment's web origin, carrying Opengeni's own route shape. Anything else
+ * is left alone: an unrelated product's URL must never be described as
+ * another Opengeni.
+ */
+export function otherDeploymentLinks(
+  text: string,
+  webBaseUrl: string | null | undefined,
+): OtherDeploymentLink[] {
+  if (!webBaseUrl) return [];
+  let own: URL;
+  try {
+    own = new URL(webBaseUrl);
+  } catch {
+    return [];
+  }
+  const ownSite = siteOf(own.hostname.toLowerCase());
+  if (!ownSite) return [];
+  const found = new Map<string, OtherDeploymentLink>();
+  for (const match of text.matchAll(OPEN_GENI_LINK_PATTERN)) {
+    let url: URL;
+    try {
+      url = new URL(`https://${match[1]}${match[2]}`);
+    } catch {
+      continue;
+    }
+    const host = url.host.toLowerCase();
+    if (host === own.host.toLowerCase()) continue;
+    if (siteOf(url.hostname.toLowerCase()) !== ownSite) continue;
+    const canonical = `${match[0].split("://", 1)[0]!.toLowerCase()}://${host}${match[2]!.toLowerCase()}`;
+    if (!found.has(canonical)) found.set(canonical, { url: canonical, host });
+    if (found.size >= MAX_OTHER_DEPLOYMENT_LINKS) break;
+  }
+  return [...found.values()];
+}
+
+/**
+ * Model context for links to another Opengeni deployment. A session id from
+ * one deployment does not exist in another, so without this the agent reports
+ * "Session not found or access denied" and asks for access that no grant in
+ * this deployment can give.
+ */
+export function otherDeploymentLinkContext(
+  text: string,
+  webBaseUrl: string | null | undefined,
+): string | null {
+  const links = otherDeploymentLinks(text, webBaseUrl);
+  if (links.length === 0 || !webBaseUrl) return null;
+  const ownHost = new URL(webBaseUrl).host.toLowerCase();
+  return [
+    `Links to a different Opengeni deployment (this one is ${ownHost}):`,
+    ...links.map((link) => `- ${link.url} is on ${link.host}.`),
+    `Workspaces, sessions and files from another deployment do not exist here, so looking up their ids in this deployment always fails as not found. Tell the user the link is for ${[...new Set(links.map((link) => link.host))].join(" and ")}, not ${ownHost}, instead of reporting the session as missing or asking for access to it.`,
+  ].join("\n");
+}