@opengeni/sdk 3.1.0 → 3.1.2

package/dist/session-message-search.d.ts

@@ -0,0 +1,53 @@
+/** Literal Unicode case-insensitive substring. Whitespace is significant. */
+export type SessionMessageSearchRequest = {
+    query: string;
+    sessionId?: string | undefined;
+    /** Workspace-only first hit per session; cannot combine with sessionId. */
+    groupBy?: "session" | undefined;
+    archiveStatus?: "active" | "archived" | "all" | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+};
+export type SessionMessageSearchMatch = {
+    sessionId: string;
+    sessionTitle: string | null;
+    eventId: string;
+    sequence: number;
+    turnId: string | null;
+    role: "user" | "assistant";
+    messageId: string | null;
+    /** Zero-based UTF-16 offset in the complete visible message. */
+    messageMatchOffset: number;
+    /** Zero-based UTF-16 offsets in text; matchEnd is exclusive. */
+    snippet: {
+        text: string;
+        matchStart: number;
+        matchEnd: number;
+    };
+};
+export type SessionMessageSearchResponse = {
+    matches: SessionMessageSearchMatch[];
+    nextCursor: string | null;
+    /** Empty advancing pages are valid. Continue until false. */
+    hasMore: boolean;
+    /** Cumulative distinct messages visited in this live traversal. */
+    scannedMessages: number;
+    /** Cumulative matching messages, or session representatives with groupBy=session. */
+    matchedMessageCount: number;
+    /** Cumulative occurrences, or session representatives with groupBy=session. */
+    matchedOccurrenceCount: number;
+    /** True only on exhaustion. Concurrent mutations require a fresh traversal. */
+    countIsExact: boolean;
+};
+/** Exact selected event reference from a search match; no payload fields are read. */
+export type SessionMessagePreviewReference = {
+    eventId: string;
+    sequence: number;
+};
+/** A complete visible message, or an explicit over-12,000-UTF-16-unit result. */
+export type SessionMessagePreview = {
+    status: "available";
+    text: string;
+} | {
+    status: "unavailable";
+};

package/dist/session-proxy-client.d.ts

@@ -0,0 +1,28 @@
+import type { OpenGeniEmbeddingClient } from "./embedding-client.js";
+import type { OpenGeniRequestOptions, FetchResponse } from "./client.js";
+import type { AccessGrant } from "./types.js";
+/** Maximum actual UTF-8 bytes forwarded for one embedded Site HTML response. */
+export declare const SESSION_PROXY_SITE_HTML_MAX_BYTES: number;
+/** A streaming Site download exceeded the host proxy's actual-byte ceiling. */
+export declare class SessionProxySiteHtmlTooLargeError extends Error {
+    readonly code = "site_html_too_large";
+    readonly limitBytes: number;
+    constructor();
+}
+/** Server-only effective grant read; never derive external authority from access/me snapshots. */
+export declare function getSessionProxyWorkspaceGrant(client: Pick<OpenGeniEmbeddingClient, "requestJson">, workspaceId: string, options?: OpenGeniRequestOptions): Promise<AccessGrant>;
+/**
+ * Exact association read. The API reauthorizes the source session on every
+ * call. `retained` proves a generated image or video, or a published sandbox
+ * file, originated in that session.
+ */
+export declare function getSessionProxyArtifactAssociation(client: Pick<OpenGeniEmbeddingClient, "requestJson">, workspaceId: string, sessionId: string, kind: "editable" | "site" | "retained", artifactId: string, options?: OpenGeniRequestOptions): Promise<{
+    sessionId: string;
+    artifactId: string;
+    kind: "editable" | "site" | "retained";
+}>;
+/** Authenticated response stream for the server proxy; does not buffer Site HTML. */
+export declare function downloadSessionProxySiteHtml(client: Pick<OpenGeniEmbeddingClient, "requestJsonResponse">, workspaceId: string, artifactId: string, options: {
+    versionId: string;
+    signal?: AbortSignal;
+}): Promise<FetchResponse>;

package/dist/session-proxy.d.ts

@@ -0,0 +1,334 @@
+import type { OpenGeniEmbeddingClient } from "./embedding-client.js";
+import { type Chats } from "./chats.js";
+import type { WorkspaceIdOptions, WorkspaceIdTarget } from "./tenant-workspaces.js";
+import type { CreateSessionRequest, FileResourceRef, LatencyMode, ReasoningEffort, SessionMcpCredentialUpdateInput } from "./types.js";
+export { downloadSessionProxySiteHtml, getSessionProxyArtifactAssociation, getSessionProxyWorkspaceGrant, SESSION_PROXY_SITE_HTML_MAX_BYTES, SessionProxySiteHtmlTooLargeError, } from "./session-proxy-client.js";
+/**
+ * Packaged same-origin backend for the React conversation surfaces.
+ *
+ * Mount the handler at a catch-all route (for example `/api/opengeni/*`) and
+ * point an unmodified browser `OpenGeniClient({ baseUrl: "/api/opengeni" })`
+ * at it. Every request is authenticated by the host's `resolve` hook, pinned
+ * to the resolved workspace, executed as the resolved external user through
+ * `asUser` (never the organization key's own service authority), and limited
+ * to the exact native routes `SessionConversation` and its hooks use. It is
+ * an explicit dispatcher, not an arbitrary upstream proxy.
+ */
+type ProxyClient = OpenGeniEmbeddingClient;
+/** The `@opengeni/sdk/chat` `Opengeni` facade, structurally. */
+type ProxyFacade = {
+    readonly client: ProxyClient;
+    readonly source: string;
+    workspaceId(target: {
+        tenant: string;
+    }): Promise<string>;
+    workspaceIdFor?(target: WorkspaceIdTarget, options: WorkspaceIdOptions): Promise<string>;
+};
+/**
+ * Who the authenticated request acts as, in your own ids. Never derive any of
+ * it from the request body or path. `{ user, tenant }`: one workspace per
+ * tenant. `{ user }`: one workspace per user. `{ user, workspaceId }`: your
+ * own workspace. Tenant and per-user mapping require the `Opengeni` facade
+ * from `@opengeni/sdk/chat`; workspaces are created on first use and Opengeni
+ * adds the user on their first request.
+ */
+export type SessionProxyResolution = ({
+    workspaceId: string;
+    tenant?: undefined;
+} | {
+    tenant: string;
+    workspaceId?: undefined;
+} | {
+    tenant?: undefined;
+    workspaceId?: undefined;
+}) & {
+    /** Host-authenticated external user id; every call runs through `asUser(user)`. */
+    user: string;
+    /** External identity source. Defaults to the facade's `source`, else `"default"`. */
+    source?: string | undefined;
+    /**
+     * The user is an anonymous visitor your product has not signed in, for
+     * example a website visitor keyed by a cookie. Visitors cannot upload
+     * composer file attachments unless the handler sets `visitorUploads: true`;
+     * everything else is unchanged.
+     */
+    visitor?: boolean | undefined;
+};
+/** Host auth hook: return the resolution, or a `Response` (for example 401) to reject. */
+export type SessionProxyResolve = (request: Request) => Promise<SessionProxyResolution | Response> | SessionProxyResolution | Response;
+export type SessionProxyContext = {
+    request: Request;
+    workspaceId: string;
+    user: string;
+    source: string;
+    /** The `asUser` client the proxy uses for this request. */
+    client: ProxyClient;
+};
+/**
+ * The only fields a browser may send when creating a session through the proxy.
+ * 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,
+ * exactly as follow-up messages carry them. Return a `Response` from the hook
+ * to refuse an input.
+ */
+export type SessionProxyCreateInput = {
+    /** Empty for a voice-first session; no initial user message is fabricated. */
+    initialMessage: string;
+    /** Available only while the proxy permits realtime voice. */
+    startMode?: "realtime" | undefined;
+    /** Browser retry key; replay is scoped to the acting user by the API. */
+    idempotencyKey?: string | undefined;
+    /** Files attached to the first message (uploaded through this proxy). */
+    resources?: FileResourceRef[] | undefined;
+    /** The user's model choice; only when `modelSelection` is not `false`. */
+    model?: string | undefined;
+    /** The user's reasoning choice; only when `modelSelection` is not `false`. */
+    reasoningEffort?: ReasoningEffort | undefined;
+    /** The user's latency choice; only when `modelSelection` is not `false`. */
+    latencyMode?: LatencyMode | undefined;
+};
+/** Which browser action is about to forward a user message or response. */
+export type SessionProxyMessageInput = {
+    /** Absent for `create`. */
+    sessionId?: string | undefined;
+    /** An empty voice-first session shell, not an initial model-producing turn. */
+    startMode?: "realtime" | undefined;
+    /**
+     * `realtime` is live voice: once when a call starts (refuse it, or rotate
+     * MCP credentials), and before each batch of finalized transcripts and spoken
+     * requests is saved (refuse it, or add `modelContext`).
+     */
+    delivery: "create" | "send" | "steer" | "submit" | "realtime";
+};
+/** Server-side additions the host attaches to one forwarded user message or response. */
+export type SessionProxyMessageExtras = {
+    /**
+     * Model-visible context for this message (current page, time zone, today's
+     * date). Placed before any context the browser sent. Not secret. Ignored for
+     * approval decisions and human-input responses, which are not new messages,
+     * and when a live voice call starts. Keep it stable for the same message:
+     * a retried voice entry must carry the same context to be accepted.
+     */
+    modelContext?: string | undefined;
+    /**
+     * Header-only credential rotation for MCP servers already attached to the
+     * session (for example a fresh short-lived per-user bearer), applied
+     * atomically as the message or response is accepted. Ignored for `create`,
+     * where the `createSession` hook sets the initial headers.
+     */
+    mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[] | undefined;
+};
+/**
+ * Your product's own MCP tool server, attached to every session this proxy
+ * creates with a per-user bearer token. Verify it on every MCP request with
+ * `verifyToolRequest` from `@opengeni/sdk/tool-auth`. Tools always act as the
+ * chat's creator: in a shared chat, other members' messages do not change it.
+ */
+export type SessionProxyToolServer = {
+    /**
+     * Public HTTPS URL of your MCP endpoint, e.g. `https://app.example.com/api/mcp`.
+     * Defaults to `OPENGENI_TOOL_SERVER_URL`, which `verifyToolRequest` also reads.
+     */
+    url?: string | undefined;
+    /** Session MCP server id (model-facing tool prefix). Defaults to `"app"`. */
+    id?: string | undefined;
+    /** Display name. */
+    name?: string | undefined;
+    /**
+     * Tools the user must approve before each call: list your write tools here
+     * (unprefixed MCP tool names), or `true` for every tool. Others run directly.
+     */
+    approvals?: {
+        ask: string[] | true;
+    } | undefined;
+    /** Token signing secret. Defaults to `OPENGENI_API_KEY`; `verifyToolRequest` must use the same. */
+    secret?: string | undefined;
+    /** Token lifetime in seconds. Defaults to 24 hours; refreshed on every message, approval, and answer. */
+    ttlSeconds?: number | undefined;
+};
+export type SessionProxyHandlerOptions = {
+    /**
+     * Private (default) uses personal Knowledge and session-only reach; shared uses
+     * workspace Knowledge and reach. Isolated also gives each user their own tenant workspace.
+     */
+    chats?: Chats | undefined;
+    /** Mandatory host auth hook, called on every request. */
+    resolve: SessionProxyResolve;
+    /**
+     * Host CSRF/session policy for non-GET requests. Without it the proxy only
+     * rejects `Sec-Fetch-Site: cross-site` mutations and requires JSON bodies;
+     * cookie-authenticated hosts should supply their existing CSRF check.
+     */
+    authorizeMutation?: ((request: Request) => boolean | Promise<boolean>) | undefined;
+    /**
+     * Optional product-level session check (for example "this ticket's session
+     * belongs to this user"). Opengeni still enforces membership and private
+     * visibility on every call.
+     */
+    authorizeSession?: ((sessionId: string, context: SessionProxyContext) => boolean | Promise<boolean>) | undefined;
+    /**
+     * Server-controlled session creation. The browser supplies only
+     * {@link SessionProxyCreateInput}; this hook returns the complete create
+     * request (agent, tools, MCP servers, Skills, instructions, model policy). Omit it
+     * to disable browser-initiated creation entirely.
+     */
+    createSession?: ((input: SessionProxyCreateInput, context: SessionProxyContext) => CreateSessionRequest | Response | Promise<CreateSessionRequest | Response>) | undefined;
+    /**
+     * Called before every forwarded user message (send, steer, composer submit,
+     * and browser-started create), approval decision, human-input response, and
+     * live voice start and transcript save (`delivery: "realtime"`).
+     * Return server-owned `modelContext` (messages and voice transcripts only)
+     * and MCP credential rotations, or a `Response` to reject the action.
+     */
+    beforeForwardMessage?: ((input: SessionProxyMessageInput, context: SessionProxyContext) => SessionProxyMessageExtras | Response | undefined | Promise<SessionProxyMessageExtras | Response | undefined>) | undefined;
+    /**
+     * Attach your product's MCP tool server to every session the `createSession`
+     * hook creates, authenticated as the resolved user. The proxy mints the
+     * token, adds the `mcpServers` entry (plus an eager ref when the hook lists
+     * explicit `tools`), and rotates the token on every send, steer, submit,
+     * approval decision, and human-input answer.
+     */
+    toolServer?: SessionProxyToolServer | undefined;
+    /** Mount prefix, e.g. `/api/opengeni`. Defaults to everything before the first `/v1/`. */
+    basePath?: string | undefined;
+    /** Maximum JSON request body. Defaults to 1 MiB. */
+    maxBodyBytes?: number | undefined;
+    /**
+     * Expose composer file attachments (upload begin/complete, download URL) and
+     * the media agents produce in a session: generated images, browser and
+     * computer screenshots, published sandbox files, and generated video
+     * playback. Workspace-level artifact reads must name their session in the
+     * `x-opengeni-session-id` header (`SessionConversation` does this); the proxy
+     * runs `authorizeSession` and only forwards an artifact Opengeni proves that
+     * session produced. Defaults to true.
+     */
+    files?: boolean | undefined;
+    /**
+     * Let anonymous visitors (`resolve` returned `visitor: true`) upload composer
+     * file attachments. Defaults to false: for a visitor the client config reports
+     * file uploads off, so stock UIs hide the attach button, and the upload routes
+     * are refused. Agent-produced media stays readable under `files`. Signed-in
+     * users follow `files` alone.
+     */
+    visitorUploads?: boolean | undefined;
+    /**
+     * Forward composer voice input (`POST .../transcriptions`, one recording per
+     * request) as the resolved user; Opengeni still requires that user's
+     * `sessions:create` permission and the workspace's voice-input setting.
+     * `false` reports voice input unavailable in the client config so stock UIs
+     * hide the microphone. Defaults to true.
+     */
+    voiceInput?: boolean | undefined;
+    /**
+     * Forward live speech-to-speech voice for existing chats as the resolved
+     * user: the voice model catalog and the call lifecycle routes under
+     * `.../sessions/{id}/realtime`. Opengeni still requires that user's
+     * `sessions:control` permission, binds the call to that user and browser,
+     * runs spoken requests as ordinary steers of the chat, and meters
+     * deployment-funded voice against the organization's credits. Defaults to
+     * true. The stock conversation's voice button is opt-in: explicit `true`
+     * reports `realtimeVoice: true` in the client config so `SessionConversation`
+     * and `OpenGeniChat` show it (when a voice model is available), as does their
+     * own `realtimeVoice` prop. `false` reports `realtimeVoice: false` so stock
+     * UIs hide it, and refuses the routes.
+     */
+    realtimeVoice?: boolean | undefined;
+    /**
+     * Let the browser read a file from the session's sandbox (`POST .../fs/read`)
+     * so `sandbox:` links in agent replies can be downloaded. Only `path`,
+     * `encoding`, and `maxBytes` are forwarded; Opengeni still requires the
+     * user's `files:read` permission on that session. Explicit opt-in, default
+     * false. Reads are confined to its working directory, including on Connected
+     * Machines; symlinked paths are refused.
+     */
+    sandboxFiles?: boolean | undefined;
+    /**
+     * Serve the embedded artifact viewer and inline Site previews: reads of the
+     * editable artifacts and Sites a session produced, and live-ticket minting
+     * for the editor. Explicit opt-in, default false.
+     *
+     * Every request must name its session in the `x-opengeni-session-id` header
+     * (`SessionArtifactViewer` and `SessionConversation` do this). The proxy
+     * runs `authorizeSession`, then only forwards an artifact Opengeni associates with
+     * that session, so the browser cannot open other workspace artifacts through
+     * it. Editing still requires the user's own `artifacts:publish` grant. Site
+     * tool calls are not proxied.
+     *
+     * The editor's live socket is ticket-authenticated and connects to Opengeni
+     * directly; the ticket binds the source session and the API revalidates its
+     * authority while connected. `editableLiveUrl` overrides the derived URL.
+     * Site HTML streams with backpressure and cancellation, with a 25 MiB
+     * actual-byte ceiling (`SESSION_PROXY_SITE_HTML_MAX_BYTES`). Oversize streams
+     * fail with `SessionProxySiteHtmlTooLargeError` / `site_html_too_large`;
+     * headers cannot be replaced once streaming has begun.
+     */
+    artifacts?: boolean | {
+        editableLiveUrl?: string | undefined;
+    } | undefined;
+    /**
+     * Read the workspace's Sites without naming a session: list, detail,
+     * content and HTML of published artifacts the signed-in user may read, for
+     * pages that belong to the workspace rather than to one chat (for example a
+     * page several sessions keep up to date, shown with `SiteDetail`). Read-only:
+     * publishing, rollback and status changes stay closed. Requests that send
+     * `x-opengeni-session-id` keep the session-scoped `artifacts` checks.
+     * Explicit opt-in, default false.
+     */
+    sites?: boolean | undefined;
+    /**
+     * Chat list for `SessionList` / `OpenGeniChat` (`listSessionPage` only).
+     * `"mine"` (default) lists sessions the resolved user created; `"visible"`
+     * lists every session Opengeni lets that user read in the workspace (shared
+     * chats included); `false` disables listing.
+     */
+    sessionList?: "mine" | "visible" | false | undefined;
+    /** Let the user archive or restore their own chats. Defaults to true. */
+    archive?: boolean | undefined;
+    /**
+     * Let the browser choose model, reasoning effort, and latency per message,
+     * draft, or new chat (still limited by the workspace model catalog). When
+     * false those choices are removed from messages and draft saves, and refused
+     * on create. Saves use the actor's
+     * server-owned draft policy (initially the session defaults). Submit must repeat
+     * the saved policy unchanged as an integrity fence, not a new selection: the
+     * API atomically checks the saved revision/content or replays the original
+     * receipt. Hide the composer's model picker to match. Defaults to true.
+     * Pass `true` explicitly to also show end users the stock model picker
+     * (`SessionConversation`/`OpenGeniChat` hide it unless asked). The picker
+     * lists the workspace's model catalog, so the workspace's allowed-model
+     * settings decide which models end users see.
+     */
+    modelSelection?: boolean | undefined;
+    /**
+     * SSE heartbeat interval. Defaults to 5 seconds, under Bun.serve's default
+     * 10-second `idleTimeout`, which otherwise closes a quiet event stream.
+     */
+    heartbeatMs?: number | undefined;
+};
+/**
+ * Create the packaged session proxy. Returns a web-standard
+ * `(Request) => Promise<Response>` for Next.js route handlers, Hono, Bun.serve,
+ * Cloudflare Workers, and similar hosts.
+ */
+export declare function createSessionProxyHandler(target: ProxyClient | ProxyFacade, options: SessionProxyHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * The client-config `artifacts` capability a custom host proxy reports so
+ * `SessionArtifactViewer` can open editable artifacts: the live socket URL
+ * (ticket-authenticated, reached directly) and the proxied user's browser cache
+ * partition. `client` acts as that user (for example `asUser(...)`).
+ */
+export declare function artifactViewerCapability(input: {
+    client: Pick<ProxyClient, "getAccessContext" | "apiUrl"> & Partial<Pick<ProxyClient, "requestJson">>;
+    workspaceId: string;
+    /** Stable namespace of the host's user identities, mixed into the partition. */
+    source?: string | undefined;
+    editableLiveUrl?: string | undefined;
+}): Promise<{
+    editableLiveUrl: string;
+    cachePartition: {
+        accountId: string;
+        principalId: string;
+        authorizationEpoch: string;
+    };
+}>;

package/dist/session-proxy.js

@@ -0,0 +1,24 @@
+import {
+  SESSION_PROXY_SITE_HTML_MAX_BYTES,
+  SessionProxySiteHtmlTooLargeError,
+  artifactViewerCapability,
+  createSessionProxyHandler,
+  downloadSessionProxySiteHtml,
+  getSessionProxyArtifactAssociation,
+  getSessionProxyWorkspaceGrant
+} from "./chunk-6HZGAIUE.js";
+import "./chunk-UM4ZXXJR.js";
+import "./chunk-QGEIL4TR.js";
+import "./chunk-4AHR4KGA.js";
+import "./chunk-KADZ5PGG.js";
+import "./chunk-7EWT3PV6.js";
+export {
+  SESSION_PROXY_SITE_HTML_MAX_BYTES,
+  SessionProxySiteHtmlTooLargeError,
+  artifactViewerCapability,
+  createSessionProxyHandler,
+  downloadSessionProxySiteHtml,
+  getSessionProxyArtifactAssociation,
+  getSessionProxyWorkspaceGrant
+};
+//# sourceMappingURL=session-proxy.js.map

package/dist/session-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/session-titles.d.ts

@@ -0,0 +1,2 @@
+export { AUTOMATIC_SESSION_TITLE_FALLBACK, deriveAutomaticSessionTitlePreview, deriveSessionDisplayTitle, sessionTitleIsPending, } from "@opengeni/contracts/session-titles";
+export type { SessionDisplayTitleInput, SessionDisplayTitleOptions, } from "@opengeni/contracts/session-titles";

package/dist/session-usage-limits.d.ts

@@ -0,0 +1,10 @@
+import type { OpenGeniClient, OpenGeniRequestOptions } from "./client.js";
+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">;
+/** Read a task's usage limit state (a child returns its root's, `inherited: true`). */
+export declare function getSessionUsageLimit(client: RequestJsonClient, workspaceId: string, sessionId: string, options?: OpenGeniRequestOptions): Promise<SessionUsageLimit>;
+/** Compare-and-set a root task's limit; `limitMicros: null` clears it. Never resumes work. */
+export declare function setSessionUsageLimit(client: RequestJsonClient, workspaceId: string, sessionId: string, request: SetSessionUsageLimitRequest): Promise<SessionUsageLimit>;

package/dist/session-usage-limits.js

@@ -0,0 +1,43 @@
+import {
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitNotConfirmed,
+  sessionUsageLimitReachedMessage
+} from "./chunk-7EWT3PV6.js";
+
+// src/session-usage-limits.ts
+function usageLimitPath(workspaceId, sessionId) {
+  return `/v1/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/usage-limit`;
+}
+async function getSessionUsageLimit(client, workspaceId, sessionId, options = {}) {
+  return await client.requestJson(
+    "GET",
+    usageLimitPath(workspaceId, sessionId),
+    void 0,
+    {},
+    options
+  );
+}
+async function setSessionUsageLimit(client, workspaceId, sessionId, request) {
+  const committed = await client.requestJson(
+    "PUT",
+    usageLimitPath(workspaceId, sessionId),
+    request
+  );
+  if (committed.limitMicros !== request.limitMicros) {
+    throw sessionUsageLimitNotConfirmed(sessionId);
+  }
+  return committed;
+}
+export {
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  formatSessionUsageMicros,
+  getSessionUsageLimit,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitReachedMessage,
+  setSessionUsageLimit
+};
+//# sourceMappingURL=session-usage-limits.js.map

package/dist/session-usage-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-usage-limits.ts"],"sourcesContent":["// @opengeni/sdk/session-usage-limits — per-task usage limit helpers that are\n// safe in browsers and React Native. Reads and writes use the root client's\n// `getSessionUsageLimit` / `setSessionUsageLimit`, or these free functions over\n// any client's `requestJson`.\n//\n// Amounts are integer USD micros of API-equivalent model usage (the\n// pre-margin provider list-price estimate), not your bill. The limit is\n// checked before each new model request: requests already running can take\n// recorded usage above it. See docs/session-usage-limits.md.\nimport type { OpenGeniClient, OpenGeniRequestOptions } from \"./client\";\nimport { sessionUsageLimitNotConfirmed } from \"./errors\";\nimport type {\n  SessionUsageLimit,\n  SetSessionUsageLimitRequest,\n} from \"@opengeni/contracts/session-usage-limits\";\n\nexport type {\n  SessionUsageLimit,\n  SessionUsageLimitHistory,\n  SessionUsageLimitReachedRefusal,\n  SessionUsageLimitStatus,\n  SetSessionUsageLimitRequest,\n} from \"@opengeni/contracts/session-usage-limits\";\nexport {\n  formatSessionUsageMicros,\n  parseSessionUsageLimitReachedRefusal,\n  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,\n  SESSION_USAGE_LIMIT_SEGMENT,\n  sessionUsageLimitReachedMessage,\n} from \"@opengeni/contracts/session-usage-limit-refusal\";\nexport type { ParsedSessionUsageLimitReachedRefusal } from \"@opengeni/contracts/session-usage-limit-refusal\";\n\ntype RequestJsonClient = Pick<OpenGeniClient, \"requestJson\">;\n\nfunction usageLimitPath(workspaceId: string, sessionId: string): string {\n  return `/v1/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/usage-limit`;\n}\n\n/** Read a task's usage limit state (a child returns its root's, `inherited: true`). */\nexport async function getSessionUsageLimit(\n  client: RequestJsonClient,\n  workspaceId: string,\n  sessionId: string,\n  options: OpenGeniRequestOptions = {},\n): Promise<SessionUsageLimit> {\n  return await client.requestJson<SessionUsageLimit>(\n    \"GET\",\n    usageLimitPath(workspaceId, sessionId),\n    undefined,\n    {},\n    options,\n  );\n}\n\n/** Compare-and-set a root task's limit; `limitMicros: null` clears it. Never resumes work. */\nexport async function setSessionUsageLimit(\n  client: RequestJsonClient,\n  workspaceId: string,\n  sessionId: string,\n  request: SetSessionUsageLimitRequest,\n): Promise<SessionUsageLimit> {\n  const committed = await client.requestJson<SessionUsageLimit>(\n    \"PUT\",\n    usageLimitPath(workspaceId, sessionId),\n    request,\n  );\n  if (committed.limitMicros !== request.limitMicros) {\n    throw sessionUsageLimitNotConfirmed(sessionId);\n  }\n  return committed;\n}\n"],"mappings":";;;;;;;;;;AAkCA,SAAS,eAAe,aAAqB,WAA2B;AACtE,SAAO,kBAAkB,mBAAmB,WAAW,CAAC,aAAa,mBAAmB,SAAS,CAAC;AACpG;AAGA,eAAsB,qBACpB,QACA,aACA,WACA,UAAkC,CAAC,GACP;AAC5B,SAAO,MAAM,OAAO;AAAA,IAClB;AAAA,IACA,eAAe,aAAa,SAAS;AAAA,IACrC;AAAA,IACA,CAAC;AAAA,IACD;AAAA,EACF;AACF;AAGA,eAAsB,qBACpB,QACA,aACA,WACA,SAC4B;AAC5B,QAAM,YAAY,MAAM,OAAO;AAAA,IAC7B;AAAA,IACA,eAAe,aAAa,SAAS;AAAA,IACrC;AAAA,EACF;AACA,MAAI,UAAU,gBAAgB,QAAQ,aAAa;AACjD,UAAM,8BAA8B,SAAS;AAAA,EAC/C;AACA,SAAO;AACT;","names":[]}

package/dist/shared-catalog-loader.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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;
+};
+export declare 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>;

package/dist/site-bridge-host.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Framework-free host side of the Site MessagePort bridge. The console's
+ * `PublishedHtmlArtifactFrame` and the published-Site gateway shell both run
+ * this code; each injects its own tool transport, Site HTTP handler, viewer
+ * provider and sign-in action.
+ *
+ * Protocol (v2): the host posts a ready message with a bootstrap port to the
+ * frame window once per document load; each SDK client connects through that
+ * port with its own MessagePort. Requests are tracked per port so a cancel or
+ * a document teardown aborts exactly the requests it owns. A second load of
+ * the same frame (a navigation inside the Site) revokes the bridge instead of
+ * handing a fresh port to an unknown document.
+ */
+import type { SiteViewer } from "@opengeni/contracts";
+import { type OpenGeniSiteBridgeReadyMessage, type OpenGeniSiteBridgeRequestMessage, type OpenGeniSiteSignInResult, type OpenGeniSiteToolCatalog } from "./site.js";
+import { type SiteHttpRequest } from "./site-http.js";
+import type { ToolGatewayCallRequest, ToolGatewayCallResponse, ToolGatewayDeclarationsResponse, ToolGatewayInvokeRequest, ToolGatewayInvokeResponse, ToolGatewayResolveRequest, ToolGatewayResolvedTool } from "./types.js";
+export type { SiteHttpRequest } from "./site-http.js";
+/** Tool and Site HTTP handlers a host supplies. Credentials stay inside these functions. */
+export type SiteBridgeToolHandlers = {
+    resolve?: (request: ToolGatewayResolveRequest, options: {
+        signal: AbortSignal;
+    }) => Promise<ToolGatewayResolvedTool>;
+    invoke?: (request: ToolGatewayInvokeRequest, options: {
+        signal: AbortSignal;
+    }) => Promise<ToolGatewayInvokeResponse>;
+    /** Serves the ordinary SDK's HTTP requests (sessions, Site Data) over the Site HTTP channel. */
+    fetch?: (request: SiteHttpRequest, signal: AbortSignal) => Promise<Response>;
+    /**
+     * Advertise Site Data and Site SQL: `fetch` serves `published-artifacts/current`
+     * routes (data, files and `sql/queries/<name>`) for the pinned Site.
+     */
+    siteData?: boolean;
+    catalog: (options: {
+        signal: AbortSignal;
+    }) => Promise<OpenGeniSiteToolCatalog>;
+    call: (request: ToolGatewayCallRequest, options: {
+        signal: AbortSignal;
+    }) => Promise<ToolGatewayCallResponse>;
+    declarations?: (options: {
+        signal: AbortSignal;
+    }) => Promise<ToolGatewayDeclarationsResponse>;
+};
+/** Viewer identity and sign-in, answered by the host itself (advertised as `viewer: 1`). */
+export type SiteBridgeViewerHandlers = {
+    viewer: (options: {
+        signal: AbortSignal;
+    }) => Promise<SiteViewer> | SiteViewer;
+    /** Defaults to `{ started: false }`: the viewer is already signed in or the host has no sign-in. */
+    signIn?: (options: {
+        signal: AbortSignal;
+    }) => Promise<OpenGeniSiteSignInResult> | OpenGeniSiteSignInResult;
+};
+export type SiteBridgeRequestValue = OpenGeniSiteToolCatalog | ToolGatewayCallResponse | ToolGatewayDeclarationsResponse | ToolGatewayResolvedTool | ToolGatewayInvokeResponse | SiteViewer | OpenGeniSiteSignInResult;
+/** Capabilities the host advertises when a Site connects; Sites never ask for more. */
+export declare function siteBridgeReadyMessage(bridge: SiteBridgeToolHandlers | undefined, viewer?: SiteBridgeViewerHandlers): OpenGeniSiteBridgeReadyMessage;
+/**
+ * The inline script a host puts at the top of Site HTML. It accepts exactly
+ * one ready message with one port from the parent window and keeps that port
+ * on a window global so SDK clients created later can still connect.
+ */
+export declare const SITE_BRIDGE_BOOTSTRAP_SCRIPT: string;
+/** Insert the bootstrap script right after a leading doctype (or at the start). */
+export declare function injectSiteBridgeBootstrap(html: string): string;
+export type SiteBridgeHostSource = {
+    /** Read on every request, so a host can swap handlers without reconnecting the Site. */
+    tools: () => SiteBridgeToolHandlers | undefined;
+    viewer?: () => SiteBridgeViewerHandlers | undefined;
+};
+/**
+ * One frame's bridge host. Call `load(frame.contentWindow)` from the frame's
+ * load event and `close()` when the frame goes away.
+ */
+export declare class SiteBridgeHost {
+    private readonly source;
+    private readonly requests;
+    private readonly lease;
+    constructor(source: SiteBridgeHostSource, options?: {
+        createMessageChannel?: () => MessageChannel;
+    });
+    /** Offer the bootstrap port to a freshly loaded document. Returns false (and revokes) on reload. */
+    load(frameWindow: Pick<Window, "postMessage">): boolean;
+    close(): void;
+    private attachToolPort;
+}
+export declare class SiteBridgeRequestRegistry {
+    private readonly controllersByPort;
+    addPort(port: MessagePort): void;
+    start(port: MessagePort, requestId: string): AbortController | null;
+    cancel(port: MessagePort, requestId: string): void;
+    complete(port: MessagePort, requestId: string, controller: AbortController): void;
+    closePort(port: MessagePort): void;
+    closeAll(): void;
+}
+export declare class SiteBridgeDocumentLease {
+    private readonly attachToolPort;
+    private readonly closeActivePorts;
+    private readonly createMessageChannel;
+    private loaded;
+    private bootstrapPort;
+    constructor(attachToolPort: (data: unknown, ports: readonly MessagePort[]) => void, closeActivePorts: () => void, createMessageChannel?: () => MessageChannel);
+    load(frameWindow: Pick<Window, "postMessage">): boolean;
+    close(): void;
+}
+export declare function openGeniSiteBridgePortFromBootstrap(data: unknown, ports: readonly MessagePort[]): MessagePort | null;
+export declare function handleSiteBridgeRequest(bridge: SiteBridgeToolHandlers | undefined, message: OpenGeniSiteBridgeRequestMessage, signal: AbortSignal, viewer?: SiteBridgeViewerHandlers): Promise<SiteBridgeRequestValue>;
+export declare function siteBridgeError(error: unknown, legacyCall?: boolean): {
+    code: string;
+    message: string;
+    retryable: boolean;
+    outcomeUnknown: boolean;
+};