@opengeni/sdk 3.3.2 → 3.4.0

package/src/session-titles.ts

@@ -1,84 +1,10 @@
-import {
+export {
   AUTOMATIC_SESSION_TITLE_FALLBACK,
-  boundAutomaticSessionTitle,
-  containsSensitiveAutomaticSessionTitleValue,
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  sessionTitleIsPending,
+} from "@opengeni/contracts/session-titles";
+export type {
+  SessionDisplayTitleInput,
+  SessionDisplayTitleOptions,
 } from "@opengeni/contracts/session-titles";
-import type { Session } from "./types";
-
-export { AUTOMATIC_SESSION_TITLE_FALLBACK };
-
-// Session creation accepts a body far larger than a navigation label. Bound
-// the source before any replace/split/normalization so a persisted large prompt
-// cannot amplify memory or CPU on every browser render.
-const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
-
-function deriveOpeningPromptPreview(value: unknown): string | null {
-  if (typeof value !== "string") return null;
-
-  const firstLine = value
-    .slice(0, PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS)
-    .replace(/[\u0000-\u001f\u007f-\u009f]+/gu, "\n")
-    .split(/\n+/u)
-    .map((line) => line.trim())
-    .find(Boolean);
-  if (!firstLine) return null;
-  if (containsSensitiveAutomaticSessionTitleValue(firstLine)) return null;
-
-  const preview = boundAutomaticSessionTitle(firstLine.replace(/\s+/gu, " "))
-    .replace(/[\s.!?,;:\-–—]+$/u, "")
-    .trim();
-  if (!preview) return null;
-  return preview;
-}
-
-export type SessionDisplayTitleInput = {
-  title?: Session["title"] | undefined;
-  titleSource?: Session["titleSource"] | undefined;
-  initialMessage?: Session["initialMessage"] | null | undefined;
-  metadata?: Readonly<Record<string, unknown>> | undefined;
-};
-
-export type SessionDisplayTitleOptions = {
-  /** Optional metadata fields to try before the opening-prompt preview. */
-  metadataKeys?: readonly string[] | undefined;
-};
-
-/**
- * Whether the durable title still represents the automatic-title pending state.
- * A user-authored title always wins, even when its literal value is the fallback.
- */
-export function sessionTitleIsPending(input: SessionDisplayTitleInput): boolean {
-  const title = input.title?.trim() ?? "";
-  return input.titleSource !== "user" && (!title || title === AUTOMATIC_SESSION_TITLE_FALLBACK);
-}
-
-/**
- * Derive the title a client should display for a session.
- *
- * A semantic agent title or human rename wins. While automatic naming is still
- * pending, clients show a short, sensitive-safe preview of the opening prompt;
- * the preview is never persisted as title metadata and is replaced naturally
- * when `session.title_set` arrives. Obvious credential-, URL-, or identifier-
- * shaped prompt prefixes retain the generic fallback.
- */
-export function deriveSessionDisplayTitle(
-  input: SessionDisplayTitleInput,
-  options: SessionDisplayTitleOptions = {},
-): string {
-  const title = input.title?.trim() ?? "";
-  if (input.titleSource === "user") {
-    return title || AUTOMATIC_SESSION_TITLE_FALLBACK;
-  }
-  if (title && !sessionTitleIsPending(input)) {
-    return title;
-  }
-
-  for (const key of options.metadataKeys ?? []) {
-    const value = input.metadata?.[key];
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value.trim();
-    }
-  }
-
-  return deriveOpeningPromptPreview(input.initialMessage) ?? AUTOMATIC_SESSION_TITLE_FALLBACK;
-}

package/src/session-usage-limits.ts

@@ -0,0 +1,71 @@
+// @opengeni/sdk/session-usage-limits — per-task usage limit helpers that are
+// safe in browsers and React Native. Reads and writes use the root client's
+// `getSessionUsageLimit` / `setSessionUsageLimit`, or these free functions over
+// any client's `requestJson`.
+//
+// Amounts are integer USD micros of API-equivalent model usage (the
+// pre-margin provider list-price estimate), not your bill. The limit is
+// checked before each new model request: requests already running can take
+// recorded usage above it. See docs/session-usage-limits.md.
+import type { OpenGeniClient, OpenGeniRequestOptions } from "./client";
+import { sessionUsageLimitNotConfirmed } from "./errors";
+import type {
+  SessionUsageLimit,
+  SetSessionUsageLimitRequest,
+} from "@opengeni/contracts/session-usage-limits";
+
+export type {
+  SessionUsageLimit,
+  SessionUsageLimitHistory,
+  SessionUsageLimitReachedRefusal,
+  SessionUsageLimitStatus,
+  SetSessionUsageLimitRequest,
+} from "@opengeni/contracts/session-usage-limits";
+export {
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  sessionUsageLimitReachedMessage,
+} from "@opengeni/contracts/session-usage-limit-refusal";
+export type { ParsedSessionUsageLimitReachedRefusal } from "@opengeni/contracts/session-usage-limit-refusal";
+
+type RequestJsonClient = Pick<OpenGeniClient, "requestJson">;
+
+function usageLimitPath(workspaceId: string, sessionId: string): string {
+  return `/v1/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/usage-limit`;
+}
+
+/** Read a task's usage limit state (a child returns its root's, `inherited: true`). */
+export async function getSessionUsageLimit(
+  client: RequestJsonClient,
+  workspaceId: string,
+  sessionId: string,
+  options: OpenGeniRequestOptions = {},
+): Promise<SessionUsageLimit> {
+  return await client.requestJson<SessionUsageLimit>(
+    "GET",
+    usageLimitPath(workspaceId, sessionId),
+    undefined,
+    {},
+    options,
+  );
+}
+
+/** Compare-and-set a root task's limit; `limitMicros: null` clears it. Never resumes work. */
+export async function setSessionUsageLimit(
+  client: RequestJsonClient,
+  workspaceId: string,
+  sessionId: string,
+  request: SetSessionUsageLimitRequest,
+): Promise<SessionUsageLimit> {
+  const committed = await client.requestJson<SessionUsageLimit>(
+    "PUT",
+    usageLimitPath(workspaceId, sessionId),
+    request,
+  );
+  if (committed.limitMicros !== request.limitMicros) {
+    throw sessionUsageLimitNotConfirmed(sessionId);
+  }
+  return committed;
+}

package/src/shared-catalog-loader.ts

@@ -0,0 +1,169 @@
+/**
+ * Single-flight loader for one digest-pinned tool catalog.
+ *
+ * - Concurrent cold callers share one request instead of each fetching.
+ * - A waiter's AbortSignal cancels only its own wait. The shared request is
+ *   cancelled once every waiter has aborted, and the next caller then starts
+ *   a new request. A waiter without a signal keeps the shared request alive
+ *   for every joiner until it settles (bounded by transport/server timeouts).
+ * - A failed load is never cached; the next caller starts a new request.
+ * - An explicit refresh, or a stale rejection, always obtains a catalog from a
+ *   request started after that refresh/rejection. Callers rejected on the same
+ *   stale digest share one post-rejection request while it is still current.
+ * - A load started before an invalidation never overwrites the newer state.
+ */
+export type SharedCatalogLoader<T extends { digest: string }> = {
+  load(options?: { refresh?: boolean; signal?: AbortSignal }): Promise<T>;
+  /** Reload after the server rejected `staleDigest` as a stale catalog. */
+  reloadAfterStale(staleDigest: string, signal?: AbortSignal): Promise<T>;
+  /** Drop the cached catalog when it is `digest`, without fetching. */
+  invalidate(digest: string): void;
+};
+
+type SharedLoad<T> = {
+  epoch: number;
+  promise: Promise<T>;
+  controller: AbortController;
+  waiters: number;
+  settled: boolean;
+};
+
+export function createSharedCatalogLoader<T extends { digest: string }>(
+  /**
+   * `refresh` is true when this load follows an invalidation or explicit
+   * refresh. `signal` aborts only when every waiter has abandoned the load.
+   */
+  fetchCatalog: (refresh: boolean, signal: AbortSignal) => Promise<T>,
+): SharedCatalogLoader<T> {
+  let snapshot: T | null = null;
+  let epoch = 0;
+  let refreshPending = false;
+  let inFlight: SharedLoad<T> | null = null;
+  let staleReload: {
+    staleDigest: string;
+    load: SharedLoad<T>;
+    settled: T | null;
+  } | null = null;
+
+  const start = (): SharedLoad<T> => {
+    if (inFlight && inFlight.epoch === epoch) return inFlight;
+    const refresh = refreshPending;
+    const load = {
+      epoch,
+      controller: new AbortController(),
+      waiters: 0,
+      settled: false,
+    } as SharedLoad<T>;
+    inFlight = load;
+    load.promise = (async () => {
+      try {
+        const next = await fetchCatalog(refresh, load.controller.signal);
+        // An abandoned load (every waiter aborted) never writes shared state,
+        // even when its transport ignored the abort and settled late.
+        if (load.epoch === epoch && !load.controller.signal.aborted) {
+          snapshot = next;
+          refreshPending = false;
+        }
+        return next;
+      } finally {
+        load.settled = true;
+        if (inFlight === load) inFlight = null;
+      }
+    })();
+    // Every waiter observes rejection itself; never leave an unobserved one.
+    load.promise.catch(() => undefined);
+    return load;
+  };
+
+  const abandon = (load: SharedLoad<T>, reason: unknown): void => {
+    if (inFlight === load) inFlight = null;
+    if (staleReload?.load === load) staleReload = null;
+    load.controller.abort(reason);
+  };
+
+  const wait = (load: SharedLoad<T>, signal: AbortSignal | undefined): Promise<T> => {
+    if (signal?.aborted) return Promise.reject(abortReason(signal));
+    load.waiters += 1;
+    return new Promise<T>((resolve, reject) => {
+      let released = false;
+      const release = (): boolean => {
+        if (released) return false;
+        released = true;
+        load.waiters -= 1;
+        signal?.removeEventListener("abort", onAbort);
+        return true;
+      };
+      const onAbort = () => {
+        if (!release()) return;
+        const reason = abortReason(signal!);
+        reject(reason);
+        if (load.waiters === 0 && !load.settled) abandon(load, reason);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      load.promise.then(
+        (value) => {
+          if (release()) resolve(value);
+        },
+        (error: unknown) => {
+          if (release()) reject(error);
+        },
+      );
+    });
+  };
+
+  const advance = (): void => {
+    snapshot = null;
+    epoch += 1;
+    refreshPending = true;
+  };
+
+  return {
+    async load(options = {}) {
+      options.signal?.throwIfAborted();
+      if (options.refresh) advance();
+      if (snapshot) return snapshot;
+      return await wait(start(), options.signal);
+    },
+    async reloadAfterStale(staleDigest, signal) {
+      signal?.throwIfAborted();
+      // Share a post-rejection reload while it is still the current load, or
+      // while its result is still the current catalog; never reuse a
+      // superseded load or result.
+      const shared = staleReload;
+      if (
+        shared?.staleDigest === staleDigest &&
+        (shared.settled === null ? shared.load.epoch === epoch : shared.settled === snapshot)
+      ) {
+        return await wait(shared.load, signal);
+      }
+      advance();
+      const load = start();
+      const reload: { staleDigest: string; load: SharedLoad<T>; settled: T | null } = {
+        staleDigest,
+        load,
+        settled: null,
+      };
+      staleReload = reload;
+      load.promise.then(
+        (next) => {
+          // The same digest again proves nothing newer; a later rejection must
+          // start its own request rather than reuse this one.
+          if (staleReload !== reload) return;
+          if (next.digest === staleDigest) staleReload = null;
+          else reload.settled = next;
+        },
+        () => {
+          if (staleReload === reload) staleReload = null;
+        },
+      );
+      return await wait(load, signal);
+    },
+    invalidate(digest) {
+      if (snapshot?.digest === digest) advance();
+    },
+  };
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}

package/src/site-ai.ts

@@ -0,0 +1,284 @@
+import type { OpenGeniClient } from "./client";
+import { ChatTurnFold, asRecord, type ChatTurnTerminal } from "./chat/fold";
+import { sessionEventStreamCoveredThrough } from "./stream";
+import type { CreateSessionRequest, Session, SessionEvent } from "./types";
+
+/** App-authored input, unchanged: no built-in tasks, prompt templates or UI. */
+export type OpenGeniSiteAiRequest = Pick<
+  CreateSessionRequest,
+  "initialMessage" | "idempotencyKey" | "model" | "reasoningEffort" | "latencyMode"
+> & { initialMessage: string };
+
+export type OpenGeniSiteAiResult = {
+  sessionId: string;
+  turnId: string | null;
+  text: string;
+  status: "completed" | "pending" | "cancelled";
+  /** Cursor for subsequent output. Resuming after it returns a suffix, not earlier text. */
+  after: number;
+};
+
+export type OpenGeniSiteAiOptions = {
+  /** Stops observing, not the underlying work. Use the ordinary session control API to cancel. */
+  signal?: AbortSignal;
+  /** Retain the handle before waiting for output, including when observation is interrupted. */
+  onSession?: (sessionId: string) => void;
+  /** Append-only answer text, folded by the same SDK implementation as embedded chat. */
+  onText?: (text: string) => void;
+};
+
+export type OpenGeniSiteAi = {
+  /** Starts an ordinary viewer-owned Site session and returns its first turn's output. */
+  run(
+    request: OpenGeniSiteAiRequest,
+    options?: OpenGeniSiteAiOptions,
+  ): Promise<OpenGeniSiteAiResult>;
+  /** Observe without sending work. Omit `after` to replay the complete answer;
+   * with `after`, text/onText contain only subsequent output. Pass the retained
+   * turnId when resuming a pending turn, so another turn cannot settle it. */
+  result(
+    sessionId: string,
+    options?: OpenGeniSiteAiOptions & { after?: number; turnId?: string },
+  ): Promise<OpenGeniSiteAiResult>;
+};
+
+/** Native create, session state and replayable events; the host remains the authority. */
+export function createOpenGeniSiteAi(
+  client: Pick<OpenGeniClient, "createSession" | "getSession" | "listEventPage" | "streamEvents">,
+  workspaceId: string,
+): OpenGeniSiteAi {
+  const result: OpenGeniSiteAi["result"] = async (sessionId, options = {}) => {
+    options.signal?.throwIfAborted();
+    const upstream = new AbortController();
+    const onAbort = () => upstream.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    const cutoff = options.after ?? 0;
+    let after = 0;
+    let text = "";
+    let fold =
+      options.turnId || cutoff === 0
+        ? new ChatTurnFold(workspaceId, sessionId, options.turnId ?? null)
+        : null;
+    // Without a retained turn id, select the first turn after the cursor, as
+    // live observation does. Keep the prefix only until that turn is known.
+    let prefix: SessionEvent[] = [];
+    let terminal: ChatTurnTerminal | null = null;
+    const pending: { event: SessionEvent | null } = { event: null };
+    let stream: ReturnType<OpenGeniClient["streamEvents"]> | undefined;
+    let streamAbort: AbortController | undefined;
+    const closeStream = () => {
+      streamAbort?.abort();
+      // Some fetch implementations await request abort in iterator.return().
+      // Abort first, and never make result delivery depend on its unwinding.
+      if (stream) void Promise.resolve(stream.return(undefined)).catch(() => undefined);
+      stream = undefined;
+      streamAbort = undefined;
+    };
+    const onUpstreamAbort = () => streamAbort?.abort(upstream.signal.reason);
+    upstream.signal.addEventListener("abort", onUpstreamAbort);
+    const emit = (chunks: ReturnType<ChatTurnFold["push"]>["chunks"]) => {
+      for (const chunk of chunks)
+        if (chunk.type === "text") {
+          upstream.signal.throwIfAborted();
+          text += chunk.text;
+          options.onText?.(chunk.text);
+        }
+    };
+    const selectTurn = (turnId: string | null) => {
+      fold = new ChatTurnFold(workspaceId, sessionId, turnId);
+      for (const event of prefix) {
+        const step = fold.push(event);
+        if (step.terminal && step.terminal !== "pending") terminal = step.terminal;
+      }
+      prefix = [];
+    };
+    const consume = (event: SessionEvent) => {
+      const covered = eventCursor(event);
+      if (covered <= after) return;
+      after = covered;
+      if (!fold) {
+        if (covered <= cutoff) {
+          prefix.push(event);
+          return;
+        }
+        if (!isTurnOutput(event) && !isWait(event)) return;
+        selectTurn(event.turnId ?? lastTurnId(prefix));
+      }
+      const current = fold!;
+      const sameTurn = !event.turnId || !current.turnId || event.turnId === current.turnId;
+      if (sameTurn && isWait(event)) {
+        if (!current.turnId && event.turnId) current.turnId = event.turnId;
+        if (event.type !== "session.status.changed") pending.event = event;
+        // A historical wait is not a settlement. Only fold it here when
+        // rebuilding text the caller already observed before their cursor.
+        if (covered > cutoff) return;
+      }
+      const step = current.push(event);
+      if (covered > cutoff) emit(step.chunks);
+      if (step.terminal && step.terminal !== "pending") terminal = step.terminal;
+    };
+    const reply = (status: ChatTurnTerminal): OpenGeniSiteAiResult => {
+      upstream.signal.throwIfAborted();
+      if (status === "failed") throw fold!.failureError();
+      return {
+        sessionId,
+        turnId: fold?.turnId ?? null,
+        text,
+        status:
+          status === "pending" ? "pending" : status === "cancelled" ? "cancelled" : "completed",
+        after: Math.max(cutoff, after),
+      };
+    };
+    const readSession = () =>
+      observe(
+        () => client.getSession(workspaceId, sessionId, { fresh: true, signal: upstream.signal }),
+        upstream.signal,
+      );
+    const replayThrough = async (through: number) => {
+      while (after < through) {
+        const previous = after;
+        const page = await observe(
+          () =>
+            client.listEventPage(workspaceId, sessionId, {
+              after,
+              before: through + 1,
+              direction: "after",
+              limit: 200,
+              mode: "forensic",
+              payloadMode: "full",
+            }),
+          upstream.signal,
+        );
+        for (const event of page.events) {
+          consume(event);
+          if (terminal && after > cutoff) return;
+        }
+        // Byte-limited short pages are not EOF; follow durable coverage.
+        after = Math.max(after, page.nextAfter ?? page.coveredSequence?.last ?? 0);
+        if (after <= previous)
+          throw new Error("The Site AI event replay did not reach the session cursor.");
+      }
+    };
+    const waiting = (session: Session) =>
+      session.status === "requires_action" &&
+      (!session.activeTurnId || !fold?.turnId || session.activeTurnId === fold.turnId);
+    try {
+      let session = await readSession();
+      // Reconstruct the exact prefix separately: unlike SSE coalescing, this
+      // bounded native page read cannot merge output from both sides of cutoff.
+      await replayThrough(Math.min(cutoff, session.lastSequence));
+      if (terminal) return reply(terminal);
+      for (;;) {
+        await replayThrough(session.lastSequence);
+        if (terminal) return reply(terminal);
+        if (waiting(session)) {
+          const fresh = await readSession();
+          if (fresh.lastSequence > after) {
+            session = fresh;
+            continue;
+          }
+          if (waiting(fresh)) {
+            if (!fold) selectTurn(fresh.activeTurnId ?? lastTurnId(prefix));
+            else if (!fold.turnId) fold.turnId = fresh.activeTurnId ?? null;
+            if (pending.event && eventCursor(pending.event) > cutoff)
+              emit(fold!.push(pending.event).chunks);
+            return reply("pending");
+          }
+          session = fresh;
+        }
+        streamAbort = new AbortController();
+        stream = client.streamEvents(workspaceId, sessionId, {
+          after: Math.max(cutoff, after),
+          signal: streamAbort.signal,
+        });
+        for (;;) {
+          const next = await observe(() => stream!.next(), upstream.signal);
+          if (next.done) throw new Error("The Site AI event stream ended before the turn settled.");
+          consume(next.value);
+          if (terminal) return reply(terminal);
+          if (isWait(next.value) && (!next.value.turnId || next.value.turnId === fold?.turnId)) {
+            // Reconcile the finite durable tail before declaring a live wait.
+            // Reopen from its cursor so buffered SSE overlap cannot repeat text.
+            closeStream();
+            session = await readSession();
+            break;
+          }
+        }
+      }
+    } finally {
+      options.signal?.removeEventListener("abort", onAbort);
+      upstream.abort();
+      closeStream();
+      upstream.signal.removeEventListener("abort", onUpstreamAbort);
+    }
+  };
+  return {
+    async run(request, options = {}) {
+      options.signal?.throwIfAborted();
+      // Pick the message fields rather than forwarding a caller's extra runtime
+      // properties. Tools, ownership, credentials and limits belong to the host.
+      const session = await client.createSession(workspaceId, {
+        initialMessage: request.initialMessage,
+        idempotencyKey: request.idempotencyKey ?? crypto.randomUUID(),
+        ...(request.model === undefined ? {} : { model: request.model }),
+        ...(request.reasoningEffort === undefined
+          ? {}
+          : { reasoningEffort: request.reasoningEffort }),
+        ...(request.latencyMode === undefined ? {} : { latencyMode: request.latencyMode }),
+      });
+      options.onSession?.(session.id);
+      return await result(session.id, options);
+    },
+    result,
+  };
+}
+
+function isWait(event: SessionEvent): boolean {
+  return (
+    event.type === "session.requiresAction" ||
+    event.type === "session.humanInput.requested" ||
+    (event.type === "session.status.changed" &&
+      asRecord(event.payload).status === "requires_action")
+  );
+}
+
+function isTurnOutput(event: SessionEvent): boolean {
+  return (
+    event.type.startsWith("turn.") ||
+    event.type.startsWith("agent.") ||
+    event.type === "user.message"
+  );
+}
+
+function lastTurnId(events: SessionEvent[]): string | null {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]!;
+    if (event.turnId && (isTurnOutput(event) || isWait(event))) return event.turnId;
+  }
+  return null;
+}
+
+function eventCursor(event: SessionEvent): number {
+  return Math.max(
+    event.sequence,
+    event.coveredThrough ?? 0,
+    sessionEventStreamCoveredThrough(event) ?? 0,
+  );
+}
+
+/** Event-page reads have no signal option; observation can still stop immediately. */
+async function observe<T>(read: () => Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let onAbort: () => void = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    const value = await Promise.race([read(), aborted]);
+    signal.throwIfAborted();
+    return value;
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}