@opengeni/sdk 4.4.1 → 4.5.0

package/src/index.ts

@@ -346,6 +346,8 @@ export {
   isRetryableStreamError,
 } from "./errors";
 export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { isTransientRequestError } from "./read-retry";
+export type { OpenGeniReadRetryOptions } from "./read-retry";
 export { parseDeprecationNotice } from "./deprecation";
 export type { OpenGeniDeprecationHandler, OpenGeniDeprecationNotice } from "./deprecation";
 export {
@@ -532,6 +534,7 @@ export type {
   PublishWorkspaceArtifactVersionRequest,
   RollbackWorkspaceArtifactRequest,
   SetWorkspaceArtifactStatusRequest,
+  SiteOpenedResponse,
   UpdateWorkspaceArtifactVisibilityRequest,
   UpdateWorkspaceArtifactVisibilityResponse,
   WorkspaceArtifactVisibility,
@@ -1320,6 +1323,7 @@ export type {
   AgentTopologySession,
   SessionListResponse,
   SessionListTotals,
+  SiteConversationGroup,
   SessionListEntry,
   SessionListEntryResponse,
   SessionLineageResponse,

package/src/read-retry.ts

@@ -0,0 +1,207 @@
+import { OpenGeniApiError } from "./errors";
+
+/**
+ * Bounded retry for safe reads (`GET` and `HEAD`) that failed transiently:
+ * the request never reached a healthy server (a transport error such as a
+ * reset connection) or a gateway answered 502, 503 or 504. These are what an
+ * API rolling deploy or a short network blip look like from the client.
+ * Mutations are never retried here; they keep their outcome-unknown semantics.
+ */
+export type OpenGeniReadRetryOptions = {
+  /** Total attempts including the first. Defaults to 4; `1` disables retries. */
+  maxAttempts?: number | undefined;
+  /** Backoff before the first retry, before jitter. Defaults to 250 ms. Doubles per retry. */
+  initialDelayMs?: number | undefined;
+  /** Upper bound for one backoff delay. Defaults to 2000 ms. */
+  maxDelayMs?: number | undefined;
+  /**
+   * Total time budget measured from the first attempt. A retry, including one
+   * whose `Retry-After` asks for a longer wait, is only made when its delay
+   * still fits in the budget; otherwise the last error surfaces. Defaults to 5000 ms.
+   */
+  maxElapsedMs?: number | undefined;
+};
+
+export type ReadRetryPolicy = {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  maxElapsedMs: number;
+};
+
+export const DEFAULT_READ_RETRY_POLICY: Readonly<ReadRetryPolicy> = Object.freeze({
+  maxAttempts: 4,
+  initialDelayMs: 250,
+  maxDelayMs: 2_000,
+  maxElapsedMs: 5_000,
+});
+
+const MAX_READ_RETRY_ATTEMPTS = 10;
+const MAX_READ_RETRY_ELAPSED_MS = 60_000;
+
+function boundedNumber(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Resolve client options to a policy, or `null` when retries are off. Invalid
+ * values fall back to the defaults instead of failing client construction.
+ */
+export function resolveReadRetryPolicy(
+  options: OpenGeniReadRetryOptions | false | undefined,
+): ReadRetryPolicy | null {
+  if (options === false) return null;
+  const input = options && typeof options === "object" ? options : {};
+  const maxAttempts = Math.floor(
+    boundedNumber(
+      input.maxAttempts,
+      DEFAULT_READ_RETRY_POLICY.maxAttempts,
+      1,
+      MAX_READ_RETRY_ATTEMPTS,
+    ),
+  );
+  if (maxAttempts <= 1) return null;
+  const maxElapsedMs = boundedNumber(
+    input.maxElapsedMs,
+    DEFAULT_READ_RETRY_POLICY.maxElapsedMs,
+    0,
+    MAX_READ_RETRY_ELAPSED_MS,
+  );
+  const maxDelayMs = boundedNumber(
+    input.maxDelayMs,
+    DEFAULT_READ_RETRY_POLICY.maxDelayMs,
+    0,
+    MAX_READ_RETRY_ELAPSED_MS,
+  );
+  const initialDelayMs = boundedNumber(
+    input.initialDelayMs,
+    DEFAULT_READ_RETRY_POLICY.initialDelayMs,
+    0,
+    maxDelayMs,
+  );
+  return { maxAttempts, initialDelayMs, maxDelayMs, maxElapsedMs };
+}
+
+export function isSafeReadMethod(method: string): boolean {
+  const normalized = method.toUpperCase();
+  return normalized === "GET" || normalized === "HEAD";
+}
+
+/** Gateway statuses a rolling deploy or an overloaded upstream answers with. */
+export function isTransientGatewayStatus(status: number): boolean {
+  return status === 502 || status === 503 || status === 504;
+}
+
+// Transport failures the client itself observed (`fetch` or the response body
+// rejected with a `TypeError`). Tagged so a caller can tell them apart from a
+// `TypeError` its own code threw, which is a bug, not a transient failure.
+const transportFailures = new WeakSet<object>();
+
+/** Record that `error` is a transport failure of an API request. */
+export function markTransportFailure(error: unknown): void {
+  if (error instanceof TypeError) transportFailures.add(error);
+}
+
+// 502s the client synthesizes for a response it could not accept (a non-JSON
+// or malformed success body). The server did answer; repeating the read gives
+// the same answer, so these are definitive rather than transient.
+const invalidResponses = new WeakSet<object>();
+
+/** A 502 for a response the client received but could not accept. */
+export function invalidApiResponseError(
+  body: string,
+  options?: ConstructorParameters<typeof OpenGeniApiError>[2],
+): OpenGeniApiError {
+  const error = new OpenGeniApiError(502, body, options);
+  invalidResponses.add(error);
+  return error;
+}
+
+// Transport failure messages across browsers, Node/undici and Bun, for
+// `TypeError`s that did not pass through this client.
+const NETWORK_FAILURE_MESSAGE =
+  /failed to fetch|fetch failed|networkerror|network error|load failed|network request failed|network connection was lost|terminated|err_http2|econnreset|socket hang up/iu;
+
+/**
+ * A failure a later identical safe read can plausibly succeed after: a
+ * transport error (`fetch` or the response body rejected with a `TypeError`)
+ * or a retryable 502, 503 or 504. Auth, permission, not-found, validation,
+ * rate limits, aborts, other server errors, a success response the client
+ * could not accept, and `TypeError`s from application code are definitive and
+ * are not transient.
+ */
+export function isTransientRequestError(error: unknown): boolean {
+  if (error instanceof OpenGeniApiError) {
+    return (
+      !invalidResponses.has(error) && isTransientGatewayStatus(error.status) && error.retryable
+    );
+  }
+  if (!(error instanceof TypeError)) return false;
+  return transportFailures.has(error) || NETWORK_FAILURE_MESSAGE.test(error.message);
+}
+
+/** `Retry-After` as milliseconds from `now`, or `null` when absent or invalid. */
+export function parseRetryAfterMs(
+  value: string | null | undefined,
+  now = Date.now(),
+): number | null {
+  if (value === null || value === undefined) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    return Number.isSafeInteger(seconds) ? seconds * 1_000 : null;
+  }
+  // Otherwise only an HTTP-date (it always names the month); never a number.
+  if (!/[A-Za-z]/.test(trimmed)) return null;
+  const at = Date.parse(trimmed);
+  if (!Number.isFinite(at)) return null;
+  return Math.max(0, at - now);
+}
+
+/**
+ * The delay before retry number `retry` (1 for the first retry), or `null`
+ * when no retry fits the policy. A server `Retry-After` is honored, plus up to
+ * 20% so clients told the same instant do not all return at once; otherwise
+ * the exponential backoff is jittered to between half and all of it.
+ */
+export function readRetryDelayMs(
+  policy: ReadRetryPolicy,
+  retry: number,
+  elapsedMs: number,
+  retryAfterMs: number | null,
+  random: () => number = Math.random,
+): number | null {
+  if (retry >= policy.maxAttempts) return null;
+  let delay: number;
+  if (retryAfterMs !== null) {
+    delay = retryAfterMs * (1 + 0.2 * Math.min(Math.max(random(), 0), 1));
+  } else {
+    const base = Math.min(policy.maxDelayMs, policy.initialDelayMs * 2 ** (retry - 1));
+    delay = base / 2 + (base / 2) * Math.min(Math.max(random(), 0), 1);
+  }
+  if (elapsedMs + delay > policy.maxElapsedMs) return null;
+  return Math.round(delay);
+}
+
+/** Resolve after `ms`, or reject with the signal's reason once it aborts. */
+export function abortableReadRetryDelay(
+  ms: number,
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason ?? new DOMException("Request aborted", "AbortError"));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new DOMException("Request aborted", "AbortError"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/session-proxy.ts

@@ -95,7 +95,9 @@ export type SessionProxyContext = {
 };
 
 /**
- * The only fields a browser may send when creating a session through the proxy.
+ * The only fields a browser may send when creating a session through the proxy,
+ * besides `modelContext`, which the proxy appends after any context the hook
+ * and `messageExtras` return, as it does for follow-up messages.
  * After the `createSession` hook returns, the proxy adds the attached files to
  * the created request (deduplicated by file id) and, when `modelSelection` is
  * not `false`, applies the browser's explicit model choices over the hook's,
@@ -358,6 +360,9 @@ export type SessionProxyHandlerOptions = {
    *   pinning a chat, moving it to a project, managing projects and a chat's
    *   tool approval settings. Every other write is refused.
    * - Catalog logos are served from the Opengeni API.
+   * - Creating a chat also takes the app's own create fields: the id of its
+   *   first message and the new-chat draft revision it sent. It sends
+   *   `visibility` and `connectionAccounts` too; the server chooses both.
    */
   sessionApp?: boolean | undefined;
   /**
@@ -406,6 +411,14 @@ const CREATE_FIELDS: ReadonlySet<string> = new Set([
   "idempotencyKey",
   "resources",
   "startMode",
+  "modelContext",
+]);
+/** Extra fields the packaged session app sends on create (see `browserCreateFields`). */
+const SESSION_APP_CREATE_FIELDS: ReadonlySet<string> = new Set([
+  "visibility",
+  "clientEventId",
+  "connectionAccounts",
+  "expectedNewSessionDraftRevision",
 ]);
 const MODEL_FIELDS = ["model", "reasoningEffort", "latencyMode"] as const;
 /** The API's single-recording ceiling (25 MiB) plus multipart framing. */
@@ -1148,7 +1161,9 @@ export function createSessionProxyHandler(
         if (method !== "POST" || !options.createSession) {
           return errorJson(404, "route_not_allowed", "Not found.");
         }
-        const input = createInput(await readJsonBody(request, maxBodyBytes), modelSelection);
+        const body = await readJsonBody(request, maxBodyBytes);
+        const input = createInput(body, modelSelection, sessionAppEnabled);
+        const browser = browserCreateFields(body, sessionAppEnabled);
         if (input.startMode === "realtime" && !realtimeVoiceEnabled) {
           return errorJson(404, "route_not_allowed", "Not found.");
         }
@@ -1157,13 +1172,18 @@ export function createSessionProxyHandler(
         const created = withBrowserCreateChoices(
           toolServer ? withToolServer(hooked, toolServer, await toolToken()) : hooked,
           input,
+          browser,
         );
         const extras = await messageExtras({
           delivery: "create",
           ...(input.startMode ? { startMode: input.startMode } : {}),
         });
         if (extras instanceof Response) return extras;
-        const modelContext = joinContext(extras?.modelContext, created.modelContext);
+        const modelContext = joinContext(
+          extras?.modelContext,
+          created.modelContext,
+          browser.modelContext,
+        );
         return json(
           await client.createSession(workspaceId, {
             ...created,
@@ -2015,9 +2035,14 @@ function pick(
 function createInput(
   body: Record<string, unknown> | undefined,
   modelSelection: boolean,
+  sessionApp: boolean,
 ): SessionProxyCreateInput {
   for (const key of Object.keys(body ?? {})) {
-    if (!CREATE_FIELDS.has(key) && !(modelSelection && isModelField(key))) {
+    if (
+      !CREATE_FIELDS.has(key) &&
+      !(modelSelection && isModelField(key)) &&
+      !(sessionApp && SESSION_APP_CREATE_FIELDS.has(key))
+    ) {
       reject(
         400,
         "create_field_not_allowed",
@@ -2097,9 +2122,68 @@ function createResources(value: unknown): FileResourceRef[] {
 }
 
 /** Browser attachments are added; explicit browser model choices win, as for messages. */
+type BrowserCreateFields = {
+  modelContext?: string | undefined;
+  clientEventId?: string | undefined;
+  expectedNewSessionDraftRevision?: number | undefined;
+};
+
+/**
+ * The browser's own context and the session app's create bookkeeping. Message
+ * context is appended after the server's, as on follow-up messages. The session
+ * app also sends the id of its first message event and the revision of the
+ * new-chat draft it sent, so the API can clear that draft. It sends `visibility`
+ * and an empty `connectionAccounts` too: the server chooses both, so those are
+ * dropped, and any account selection is refused.
+ */
+function browserCreateFields(
+  body: Record<string, unknown> | undefined,
+  sessionApp: boolean,
+): BrowserCreateFields {
+  const fields: BrowserCreateFields = {};
+  const modelContext = body?.modelContext;
+  if (modelContext !== undefined && typeof modelContext !== "string") {
+    reject(400, "invalid_model_context", "modelContext must be a string.");
+  }
+  if (modelContext?.trim()) fields.modelContext = modelContext;
+  if (!sessionApp) return fields;
+  const visibility = body?.visibility;
+  if (visibility !== undefined && visibility !== "workspace" && visibility !== "private") {
+    reject(400, "invalid_visibility", "visibility must be workspace or private.");
+  }
+  const accounts = body?.connectionAccounts;
+  if (accounts !== undefined && (!Array.isArray(accounts) || accounts.length > 0)) {
+    reject(
+      403,
+      "connection_account_not_allowed",
+      "The server chooses which connected accounts a chat uses.",
+    );
+  }
+  const clientEventId = body?.clientEventId;
+  if (clientEventId !== undefined) {
+    if (typeof clientEventId !== "string" || !clientEventId) {
+      reject(400, "invalid_client_event_id", "clientEventId must be a non-empty string.");
+    }
+    fields.clientEventId = clientEventId;
+  }
+  const revision = body?.expectedNewSessionDraftRevision;
+  if (revision !== undefined) {
+    if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 0) {
+      reject(
+        400,
+        "invalid_draft_revision",
+        "expectedNewSessionDraftRevision must be a non-negative integer.",
+      );
+    }
+    fields.expectedNewSessionDraftRevision = revision;
+  }
+  return fields;
+}
+
 function withBrowserCreateChoices(
   created: CreateSessionRequest,
   input: SessionProxyCreateInput,
+  browser: BrowserCreateFields = {},
 ): CreateSessionRequest {
   const existing = created.resources ?? [];
   const attached = new Set(
@@ -2118,6 +2202,13 @@ function withBrowserCreateChoices(
     ...(input.model ? { model: input.model } : {}),
     ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
     ...(input.latencyMode ? { latencyMode: input.latencyMode } : {}),
+    ...(created.clientEventId === undefined && browser.clientEventId
+      ? { clientEventId: browser.clientEventId }
+      : {}),
+    ...(created.expectedNewSessionDraftRevision === undefined &&
+    browser.expectedNewSessionDraftRevision !== undefined
+      ? { expectedNewSessionDraftRevision: browser.expectedNewSessionDraftRevision }
+      : {}),
   };
 }