@opengeni/api-router 3.0.1 → 3.1.2

package/src/site-publishing/session-events.ts

@@ -0,0 +1,262 @@
+import { siteRuntimeForwardedResponse } from "./runtime";
+
+/**
+ * The Site-safe view of a published-Site conversation's events, shared by
+ * the event pages and the event stream so both deliver the same thing.
+ *
+ * A viewer sees the conversation, not the workspace behind it:
+ * - Only the event types a chat needs are delivered: messages (with their
+ *   live text deltas), tool-call receipts, turn and session lifecycle, the
+ *   queue and usage notices. Their payloads keep allowlisted fields only:
+ *   message text, a tool's call id and name and whether it failed (never its
+ *   arguments or output), and short status codes (never error text).
+ * - Every other event (reasoning, sandbox and terminal output, model and
+ *   provider-account telemetry, setup, goals, memory, policy and late or
+ *   duplicate deliveries) becomes a `session.event.envelope_omitted`
+ *   placeholder with an empty payload. The placeholder keeps the sequence
+ *   contiguous, so a client's gap detection and resume still work, and says
+ *   nothing about what was there.
+ * - The envelope keeps the event id, session id, sequence, coverage,
+ *   occurrence time and turn id. It drops the workspace id, attempt ids and
+ *   generations, duplicate diagnostics, codec and read-bound markers.
+ */
+
+const OMITTED_TYPE = "session.event.envelope_omitted";
+
+type FieldRule = "text" | "code" | "ref" | "count" | "flag";
+
+/** Event types a Site viewer receives, with the payload fields each keeps. */
+const SITE_EVENT_PAYLOAD_FIELDS: ReadonlyMap<string, Readonly<Record<string, FieldRule>>> = new Map<
+  string,
+  Readonly<Record<string, FieldRule>>
+>([
+  ["session.created", {}],
+  ["session.status.changed", { status: "code", previousStatus: "code", code: "code" }],
+  ["session.title_set", { title: "text" }],
+  ["session.requiresAction", {}],
+  ["session.humanInput.requested", {}],
+  ["session.queue.changed", { operation: "code", queueVersion: "count" }],
+  ["session.queue.prompt.cancelled", {}],
+  ["session.control.paused", {}],
+  ["session.control.resumed", {}],
+  ["session.control.steer_requested", {}],
+  [OMITTED_TYPE, {}],
+  ["user.message", { text: "text", delivery: "code", routing: "code" }],
+  ["user.pause", {}],
+  ["turn.queued", {}],
+  ["turn.started", {}],
+  ["turn.completed", { segmentLimit: "code", maintenance: "code" }],
+  ["turn.failed", { code: "code", failureCode: "code", retryable: "flag" }],
+  ["turn.cancelled", { reason: "code" }],
+  ["turn.superseded", { reason: "code" }],
+  [
+    "agent.message.delta",
+    { text: "text", messageId: "ref", phase: "code", coalescedUntil: "count" },
+  ],
+  ["agent.message.completed", { text: "text", messageId: "ref", phase: "code" }],
+  ["agent.toolCall.created", { id: "ref", name: "ref" }],
+  ["agent.toolCall.output", { id: "ref", name: "ref", error: "flag" }],
+  ["usage.threshold_reached", {}],
+  ["usage.exhausted", {}],
+]);
+
+/** The event types a Site viewer can receive with their content. */
+export const SITE_VISIBLE_SESSION_EVENT_TYPES: ReadonlySet<string> = new Set(
+  SITE_EVENT_PAYLOAD_FIELDS.keys(),
+);
+
+const CODE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/u;
+const REF = /^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$/u;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function allowedField(rule: FieldRule, value: unknown): boolean {
+  switch (rule) {
+    case "text":
+      return typeof value === "string";
+    case "code":
+      return typeof value === "string" && CODE.test(value);
+    case "ref":
+      return typeof value === "string" && REF.test(value);
+    case "count":
+      return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+    case "flag":
+      return typeof value === "boolean";
+  }
+}
+
+export type SiteSessionEventPayloadMode = "summary" | "none";
+
+/**
+ * Project one event for a Site viewer, or null when it is not an event at all.
+ * Hidden events become an omitted placeholder at the same sequence.
+ */
+export function siteSessionEventProjection(
+  event: unknown,
+  options: { payload?: SiteSessionEventPayloadMode } = {},
+): Record<string, unknown> | null {
+  const source = record(event);
+  if (!source) return null;
+  const { id, sequence } = source;
+  if (typeof id !== "string" || typeof sequence !== "number" || !Number.isSafeInteger(sequence))
+    return null;
+  const projected: Record<string, unknown> = {
+    id,
+    sessionId: typeof source.sessionId === "string" ? source.sessionId : null,
+    sequence,
+  };
+  const covered = source.coveredThrough;
+  if (typeof covered === "number" && Number.isSafeInteger(covered) && covered >= sequence)
+    projected.coveredThrough = covered;
+  projected.occurredAt = typeof source.occurredAt === "string" ? source.occurredAt : null;
+  const current =
+    (source.turnAssociation === undefined ||
+      source.turnAssociation === null ||
+      source.turnAssociation === "current") &&
+    (source.duplicateOfEventId === undefined || source.duplicateOfEventId === null);
+  const type = typeof source.type === "string" ? source.type : "";
+  const fields = current ? SITE_EVENT_PAYLOAD_FIELDS.get(type) : undefined;
+  if (!fields) return { ...projected, type: OMITTED_TYPE, turnId: null, payload: {} };
+  projected.type = type;
+  projected.turnId = typeof source.turnId === "string" ? source.turnId : null;
+  if (
+    type === "user.message" &&
+    typeof source.clientEventId === "string" &&
+    source.clientEventId.length <= 256
+  )
+    projected.clientEventId = source.clientEventId;
+  const payload: Record<string, unknown> = {};
+  const body = options.payload === "none" ? null : record(source.payload);
+  if (body) {
+    for (const [name, rule] of Object.entries(fields))
+      if (Object.hasOwn(body, name) && allowedField(rule, body[name])) payload[name] = body[name];
+    // A failed tool says so without its output (an MCP error result).
+    if (type === "agent.toolCall.output" && record(body.output)?.isError === true)
+      payload.error = true;
+  }
+  projected.payload = payload;
+  return projected;
+}
+
+/** Upstream SSE frames never come close to this; a stream that does is broken. */
+const SSE_BUFFER_MAX_CHARS = 8 * 1024 * 1024;
+
+function projectSseFrame(frame: string): string | null {
+  const lines = frame.split("\n");
+  // Comments (`: connected`, `: heartbeat`) keep the connection alive.
+  if (lines.every((line) => line.startsWith(":"))) return `${frame}\n\n`;
+  let id: string | null = null;
+  const data: string[] = [];
+  for (const line of lines) {
+    if (line.startsWith("id:")) id = line.slice(3).trim();
+    else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /u, ""));
+  }
+  if (data.length === 0) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data.join("\n"));
+  } catch {
+    return null;
+  }
+  const projected = siteSessionEventProjection(parsed);
+  if (!projected) return null;
+  const sequence = projected.sequence as number;
+  // The frame id is the sequence this frame covers (coalesced deltas cover a
+  // run); keep it so a reconnect resumes after everything it covered.
+  const covered = id !== null && /^\d{1,15}$/u.test(id) && Number(id) >= sequence ? id : sequence;
+  return `id: ${covered}\nevent: ${projected.type as string}\ndata: ${JSON.stringify(projected)}\n\n`;
+}
+
+/** Rewrites a session event stream (SSE or a finite SSE batch) frame by frame. */
+export function siteSessionEventSseTransform(): TransformStream<Uint8Array, Uint8Array> {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let buffer = "";
+  const drain = (controller: TransformStreamDefaultController<Uint8Array>) => {
+    let start = 0;
+    let output = "";
+    for (let end = buffer.indexOf("\n\n", start); end >= 0; end = buffer.indexOf("\n\n", start)) {
+      const frame = projectSseFrame(buffer.slice(start, end));
+      if (frame !== null) output += frame;
+      start = end + 2;
+    }
+    buffer = buffer.slice(start);
+    if (output) controller.enqueue(encoder.encode(output));
+    if (buffer.length > SSE_BUFFER_MAX_CHARS)
+      throw new Error("Session event stream frame exceeds the Site projection buffer");
+  };
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      buffer += decoder.decode(chunk, { stream: true });
+      drain(controller);
+    },
+    flush(controller) {
+      buffer += decoder.decode();
+      drain(controller);
+    },
+  });
+}
+
+/** A forwarded event stream, answered with the Site-safe projection. */
+export function siteSessionEventStreamResponse(response: Response): Response {
+  const forwarded = siteRuntimeForwardedResponse(response);
+  if (!forwarded.ok || !forwarded.body) return forwarded;
+  const headers = new Headers(forwarded.headers);
+  headers.delete("content-length");
+  return new Response(forwarded.body.pipeThrough(siteSessionEventSseTransform()), {
+    status: forwarded.status,
+    headers,
+  });
+}
+
+/** Cursor and paging facts of an event page that stay meaningful after projection. */
+const PAGE_HEADERS = [
+  "x-opengeni-event-direction",
+  "x-opengeni-page-max-bytes",
+  "x-opengeni-page-truncated",
+  "x-opengeni-has-more",
+  "x-opengeni-truncated-by",
+  "x-opengeni-covered-first",
+  "x-opengeni-covered-last",
+  "x-opengeni-next-after",
+  "x-opengeni-next-before",
+] as const;
+
+/** A forwarded event page, answered with the Site-safe projection. */
+export async function siteSessionEventPageResponse(
+  response: Response,
+  options: { payload?: SiteSessionEventPayloadMode } = {},
+): Promise<Response> {
+  if (!response.ok) return siteRuntimeForwardedResponse(response);
+  const body: unknown = await response.json().catch(() => null);
+  const events = (Array.isArray(body) ? body : [])
+    .map((event) => siteSessionEventProjection(event, options))
+    .filter((event): event is Record<string, unknown> => event !== null);
+  return siteSessionEventPage(events, options, response.headers);
+}
+
+/** A page of already projected events with monitoring-read headers. */
+export function siteSessionEventPage(
+  events: readonly Record<string, unknown>[],
+  options: { payload?: SiteSessionEventPayloadMode } = {},
+  upstream?: Headers,
+): Response {
+  const text = JSON.stringify(events);
+  const headers = new Headers({
+    "content-type": "application/json; charset=UTF-8",
+    "cache-control": "no-store",
+    "x-opengeni-event-mode": "monitoring",
+    "x-opengeni-payload-mode": options.payload === "none" ? "none" : "summary",
+    "x-opengeni-forensic-exact": "false",
+    "x-opengeni-page-bytes": String(new TextEncoder().encode(text).byteLength),
+  });
+  for (const name of PAGE_HEADERS) {
+    const value = upstream?.get(name);
+    if (value !== null && value !== undefined) headers.set(name, value);
+  }
+  return new Response(text, { status: 200, headers });
+}

package/src/site-publishing/session-views.ts

@@ -0,0 +1,262 @@
+import { siteSessionEventProjection } from "./session-events";
+
+/**
+ * Site-safe views of the session reads and command results a published
+ * Site's viewer gets back: the conversation's own text, states and versions,
+ * never the workspace behind it (account and workspace ids, workflow and
+ * attempt ids, tools, sandboxes, metadata, lineage, initiators, people's
+ * subject ids, pause reasons, credentials or human-input answers). Each view
+ * keeps the field shapes the SDK expects, with empty lists and objects where
+ * a field is withheld. Event pages and streams use the event projection in
+ * `session-events.ts`; sessions use `siteSessionProjection`.
+ */
+
+type Fields = Record<string, unknown>;
+
+function fields(value: unknown): Fields | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Fields)
+    : null;
+}
+
+function list(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function pick(value: Fields, keys: readonly string[]): Fields {
+  const out: Fields = {};
+  for (const key of keys) if (Object.hasOwn(value, key)) out[key] = value[key];
+  return out;
+}
+
+function present<T>(value: T | null): value is T {
+  return value !== null;
+}
+
+const CONTROL_FIELDS = [
+  "state",
+  "controlVersion",
+  "controlEtag",
+  "directState",
+  "additionalBlockerCount",
+  "settlement",
+  "backgroundCommandSettlement",
+] as const;
+
+/** What holds a conversation, without who did it, why, or which other sessions. */
+function siteControlBlocker(value: unknown): Fields | null {
+  const blocker = fields(value);
+  if (!blocker) return null;
+  const workspace = blocker.kind === "workspace";
+  return {
+    kind: workspace ? "workspace" : "session",
+    displayName: workspace ? "Workspace" : "Conversation",
+    actor: null,
+    reason: null,
+    changedAt: typeof blocker.changedAt === "string" ? blocker.changedAt : null,
+    revision: typeof blocker.revision === "number" ? blocker.revision : 0,
+  };
+}
+
+/** A conversation's effective control: its state and versions, and a resume of itself only. */
+export function siteControlView(value: unknown): Fields | null {
+  const control = fields(value);
+  if (!control) return null;
+  const resumeOptions = list(control.resumeOptions)
+    .map(fields)
+    .filter(present)
+    .filter((option) => option.scope === "session")
+    .map((option) => ({
+      scope: "session",
+      selectedStateAfter: option.selectedStateAfter,
+      impactCopy: "Resume this conversation.",
+    }));
+  return {
+    ...pick(control, CONTROL_FIELDS),
+    primaryBlocker: siteControlBlocker(control.primaryBlocker),
+    blockers: list(control.blockers).map(siteControlBlocker).filter(present),
+    resumeOptions,
+    override: null,
+  };
+}
+
+const TURN_FIELDS = [
+  "id",
+  "sessionId",
+  "status",
+  "source",
+  "position",
+  "prompt",
+  "model",
+  "reasoningEffort",
+  "latencyMode",
+  "version",
+  "startedAt",
+  "finishedAt",
+  "createdAt",
+  "updatedAt",
+] as const;
+
+/** A turn: its message text, model, place and state. */
+export function siteTurnView(value: unknown): Fields | null {
+  const turn = fields(value);
+  if (!turn) return null;
+  return {
+    ...pick(turn, TURN_FIELDS),
+    annotations: [],
+    resources: [],
+    tools: [],
+    metadata: {},
+    lineage: {},
+    personalConnections: [],
+    personalResources: null,
+    cancelledBy: null,
+    cancelReason: null,
+  };
+}
+
+/** The conversation's queue: its own turns, without machine inputs. */
+export function siteQueueView(value: unknown): Fields | null {
+  const queue = fields(value);
+  if (!queue) return null;
+  return {
+    version: queue.version,
+    effectiveControl: siteControlView(queue.effectiveControl),
+    activePersonalConnections: [],
+    stoppingPreviousAttempt: queue.stoppingPreviousAttempt === true,
+    items: list(queue.items).map(siteTurnView).filter(present),
+    pendingInputs: [],
+    pendingInputAttachment: null,
+  };
+}
+
+const DRAFT_FIELDS = [
+  "revision",
+  "text",
+  "model",
+  "reasoningEffort",
+  "latencyMode",
+  "sourceTurnId",
+  "sourceTurnVersion",
+  "updatedAt",
+] as const;
+
+/** A composer draft: text and model only (Site drafts carry nothing else). */
+export function siteDraftView(value: unknown): Fields | null {
+  const draft = fields(value);
+  if (!draft) return null;
+  return { ...pick(draft, DRAFT_FIELDS), annotations: [], resources: [] };
+}
+
+const RECEIPT_FIELDS = [
+  "id",
+  "action",
+  "operationKey",
+  "targetSessionId",
+  "targetTurnId",
+  "appliedControlRevision",
+  "appliedQueueVersion",
+  "appliedTurnVersion",
+  "appliedDraftRevision",
+  "createdAt",
+] as const;
+
+function siteReceiptView(value: unknown): Fields | null {
+  const receipt = fields(value);
+  return receipt ? pick(receipt, RECEIPT_FIELDS) : null;
+}
+
+const QUESTION_FIELDS = [
+  "id",
+  "kind",
+  "prompt",
+  "label",
+  "helpText",
+  "options",
+  "required",
+  "allowOther",
+  "validation",
+] as const;
+
+const HUMAN_INPUT_FIELDS = [
+  "id",
+  "sessionId",
+  "turnId",
+  "status",
+  "allowSkip",
+  "respondedAt",
+  "expiresAt",
+  "createdAt",
+  "updatedAt",
+] as const;
+
+/**
+ * A human-input request: its questions without secret specs or review
+ * references, and never the answers or who gave them (a Site does not
+ * answer; answers belong to whoever did, in the console).
+ */
+export function siteHumanInputRequestView(value: unknown): Fields | null {
+  const request = fields(value);
+  if (!request) return null;
+  return {
+    ...pick(request, HUMAN_INPUT_FIELDS),
+    questions: list(request.questions)
+      .map(fields)
+      .filter(present)
+      .map((question) => pick(question, QUESTION_FIELDS)),
+    response: null,
+    respondedBy: null,
+  };
+}
+
+/** `{ requests }` from the human-input list. */
+export function siteHumanInputListView(value: unknown): Fields {
+  return {
+    requests: list(fields(value)?.requests).map(siteHumanInputRequestView).filter(present),
+  };
+}
+
+/** A queue command result (move, edit, delete, steer). */
+export function siteQueueMutationView(value: unknown): Fields | null {
+  const result = fields(value);
+  if (!result) return null;
+  return {
+    receipt: siteReceiptView(result.receipt),
+    snapshot: siteQueueView(result.snapshot),
+    ...(result.draft === undefined ? {} : { draft: siteDraftView(result.draft) }),
+  };
+}
+
+/** An accepted message (composer submit, steer): the event, turn and routing. */
+export function siteAcceptedMessageView(value: unknown): Fields | null {
+  const result = fields(value);
+  if (!result) return null;
+  return {
+    accepted: siteSessionEventProjection(result.accepted),
+    turn: siteTurnView(result.turn),
+    ...(result.draft === undefined ? {} : { draft: siteDraftView(result.draft) }),
+    receipt: siteReceiptView(result.receipt),
+    ...pick(result, ["routing", "interruptionCount", "replay"]),
+  };
+}
+
+/** A control result: the receipt and the conversation's control. */
+export function siteControlResultView(value: unknown): Fields | null {
+  const result = fields(value);
+  if (!result) return null;
+  return {
+    receipt: siteReceiptView(result.receipt),
+    effectiveControl: siteControlView(result.effectiveControl),
+    ...pick(result, [
+      "interruptionCount",
+      "wakeCount",
+      "cancelledSessionCount",
+      "cancelledTurnCount",
+    ]),
+  };
+}
+
+/** An accepted event (`POST /events`): the Site event projection. */
+export function siteAcceptedEventView(value: unknown): Fields | null {
+  return siteSessionEventProjection(value);
+}

package/src/site-publishing/viewer.ts

@@ -0,0 +1,75 @@
+import type { SiteAccessMode, SiteViewer } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+
+/**
+ * Who may open a published Site. The API decides this on sign-in and again
+ * on every site-runtime call; the gateway's own checks are only a convenience.
+ */
+
+export type SiteViewerAccessSettings = Pick<Settings, "sitesPublicEnabled" | "sitesLoginOnly">;
+
+/** Public access needs the deployment switch; without it a public Site is members-only. */
+export function effectiveSiteAccess(
+  access: SiteAccessMode,
+  settings: SiteViewerAccessSettings,
+): SiteAccessMode {
+  return access === "public" && !settings.sitesPublicEnabled ? "members" : access;
+}
+
+/**
+ * The kind of a signed-in viewer, or null when the Site does not admit them:
+ * workspace members always; invited email addresses (verified) for invited
+ * and public Sites; anyone signed in for public Sites.
+ */
+export function signedInSiteViewerKind(input: {
+  access: SiteAccessMode;
+  member: boolean;
+  email: string | null;
+  invitedEmails: readonly string[];
+}): "member" | "invited" | "user" | null {
+  if (input.member) return "member";
+  if (
+    input.access !== "members" &&
+    input.email !== null &&
+    input.invitedEmails.includes(input.email.trim().toLowerCase())
+  )
+    return "invited";
+  return input.access === "public" ? "user" : null;
+}
+
+/** Anonymous guests reach only public Sites, and never on a login-only deployment. */
+export function siteGuestsAllowed(
+  access: SiteAccessMode,
+  settings: SiteViewerAccessSettings,
+): boolean {
+  return effectiveSiteAccess(access, settings) === "public" && !settings.sitesLoginOnly;
+}
+
+/** Gateway-minted visitor ids: opaque, URL-safe, bounded. */
+export const SITE_VISITOR_ID = /^[A-Za-z0-9_-]{16,128}$/u;
+
+export type SiteRuntimeViewer = {
+  kind: SiteViewer["kind"];
+  /** `user:<subject>` or `guest:<visitor>`: the Site Data owner and conversation owner. */
+  principal: string;
+  subjectId: string | null;
+  name: string | null;
+  email: string | null;
+  /** The site-session row when signed in. */
+  sessionId: string | null;
+  /**
+   * Set while a workspace member previews the Site as another role ("View
+   * as visitor"): the viewer is then exactly that role, never more.
+   */
+  viewAs?: "invited" | "public" | null;
+};
+
+export function publicSiteViewer(viewer: SiteRuntimeViewer): SiteViewer {
+  return {
+    kind: viewer.kind,
+    id: viewer.principal,
+    name: viewer.kind === "guest" ? null : viewer.name,
+    email: viewer.kind === "guest" ? null : viewer.email,
+    signedIn: viewer.kind !== "guest",
+  };
+}