@opengeni/sdk 3.3.2 → 3.4.0

package/dist/session-history-import.js

@@ -0,0 +1,36 @@
+// src/session-history-import.ts
+function importArchivedSession(client, workspaceId, request) {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports`,
+    request
+  );
+}
+function appendArchivedSessionEvents(client, workspaceId, importId, request) {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports/${encodeURIComponent(importId)}/events`,
+    request
+  );
+}
+function importExternalWorkspaceArchivedSession(client, source, externalId, request) {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports`,
+    request
+  );
+}
+function appendExternalWorkspaceArchivedSessionEvents(client, source, externalId, importId, request) {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports/${encodeURIComponent(importId)}/events`,
+    request
+  );
+}
+export {
+  appendArchivedSessionEvents,
+  appendExternalWorkspaceArchivedSessionEvents,
+  importArchivedSession,
+  importExternalWorkspaceArchivedSession
+};
+//# sourceMappingURL=session-history-import.js.map

package/dist/session-history-import.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-history-import.ts"],"sourcesContent":["import type { OpenGeniClient } from \"./client\";\nimport type {\n  AppendArchivedSessionEventsRequest,\n  AppendArchivedSessionEventsResponse,\n  ImportArchivedSessionRequest,\n  ImportArchivedSessionResponse,\n} from \"@opengeni/contracts\";\n\nexport type {\n  ArchivedSessionImportEvent,\n  AppendArchivedSessionEventsRequest,\n  AppendArchivedSessionEventsResponse,\n  ImportArchivedSessionRequest,\n  ImportArchivedSessionResponse,\n  SessionImportedArchive,\n} from \"@opengeni/contracts\";\n\ntype SessionHistoryImportClient = Pick<OpenGeniClient, \"requestJson\">;\n\n/**\n * Server-only migration of a read-only archive, not model-facing conversation\n * history. Use an asUser client to preserve the verified creator/owner. Persist\n * importId and retry the exact request after an uncertain outcome.\n * Requires sessions:create in the authenticated actor's permissions.\n */\nexport function importArchivedSession(\n  client: SessionHistoryImportClient,\n  workspaceId: string,\n  request: ImportArchivedSessionRequest,\n): Promise<ImportArchivedSessionResponse> {\n  return client.requestJson(\n    \"POST\",\n    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports`,\n    request,\n  );\n}\n\n/**\n * Append historical events at the acknowledged nextOffset. Retrying the exact\n * batchId, offset and events replays its receipt; conflicting reuse returns 409.\n * Each request accepts at most 100 events / 1 MiB, with 256 KiB per event.\n * Requires sessions:control and the same authenticated importer.\n */\nexport function appendArchivedSessionEvents(\n  client: SessionHistoryImportClient,\n  workspaceId: string,\n  importId: string,\n  request: AppendArchivedSessionEventsRequest,\n): Promise<AppendArchivedSessionEventsResponse> {\n  return client.requestJson(\n    \"POST\",\n    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports/${encodeURIComponent(importId)}/events`,\n    request,\n  );\n}\n\n/** Import through an existing external tenant mapping; this does not onboard it. */\nexport function importExternalWorkspaceArchivedSession(\n  client: SessionHistoryImportClient,\n  source: string,\n  externalId: string,\n  request: ImportArchivedSessionRequest,\n): Promise<ImportArchivedSessionResponse> {\n  return client.requestJson(\n    \"POST\",\n    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports`,\n    request,\n  );\n}\n\n/** Append to an archive through the same external tenant mapping and actor. */\nexport function appendExternalWorkspaceArchivedSessionEvents(\n  client: SessionHistoryImportClient,\n  source: string,\n  externalId: string,\n  importId: string,\n  request: AppendArchivedSessionEventsRequest,\n): Promise<AppendArchivedSessionEventsResponse> {\n  return client.requestJson(\n    \"POST\",\n    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports/${encodeURIComponent(importId)}/events`,\n    request,\n  );\n}\n"],"mappings":";AAyBO,SAAS,sBACd,QACA,aACA,SACwC;AACxC,SAAO,OAAO;AAAA,IACZ;AAAA,IACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,IACjD;AAAA,EACF;AACF;AAQO,SAAS,4BACd,QACA,aACA,UACA,SAC8C;AAC9C,SAAO,OAAO;AAAA,IACZ;AAAA,IACA,kBAAkB,mBAAmB,WAAW,CAAC,oBAAoB,mBAAmB,QAAQ,CAAC;AAAA,IACjG;AAAA,EACF;AACF;AAGO,SAAS,uCACd,QACA,QACA,YACA,SACwC;AACxC,SAAO,OAAO;AAAA,IACZ;AAAA,IACA,2BAA2B,mBAAmB,MAAM,CAAC,IAAI,mBAAmB,UAAU,CAAC;AAAA,IACvF;AAAA,EACF;AACF;AAGO,SAAS,6CACd,QACA,QACA,YACA,UACA,SAC8C;AAC9C,SAAO,OAAO;AAAA,IACZ;AAAA,IACA,2BAA2B,mBAAmB,MAAM,CAAC,IAAI,mBAAmB,UAAU,CAAC,oBAAoB,mBAAmB,QAAQ,CAAC;AAAA,IACvI;AAAA,EACF;AACF;","names":[]}

package/dist/session-list-entries.d.ts

@@ -0,0 +1 @@
+export { sessionListEntry } from "@opengeni/contracts/session-list-entries";

package/dist/session-list-entries.js

@@ -0,0 +1,7 @@
+import {
+  sessionListEntry
+} from "./chunk-ZDUBPV33.js";
+export {
+  sessionListEntry
+};
+//# sourceMappingURL=session-list-entries.js.map

package/dist/session-list-entries.js.map

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

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-FTWVVPR6.js";
+import "./chunk-UM4ZXXJR.js";
+import "./chunk-QGEIL4TR.js";
+import "./chunk-4AHR4KGA.js";
+import "./chunk-NCU5OAN7.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

@@ -1,28 +1,2 @@
-import { AUTOMATIC_SESSION_TITLE_FALLBACK } from "@opengeni/contracts/session-titles";
-import type { Session } from "./types.js";
-export { AUTOMATIC_SESSION_TITLE_FALLBACK };
-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 declare function sessionTitleIsPending(input: SessionDisplayTitleInput): boolean;
-/**
- * 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 declare function deriveSessionDisplayTitle(input: SessionDisplayTitleInput, options?: SessionDisplayTitleOptions): string;
+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>;