@opengeni/sdk 0.57.0 → 1.0.0

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,24 @@
+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. */
+export declare function getSessionProxyArtifactAssociation(client: Pick<OpenGeniEmbeddingClient, "requestJson">, workspaceId: string, sessionId: string, kind: "editable" | "site", artifactId: string, options?: OpenGeniRequestOptions): Promise<{
+    sessionId: string;
+    artifactId: string;
+    kind: "editable" | "site";
+}>;
+/** 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,245 @@
+import type { OpenGeniEmbeddingClient } from "./embedding-client.js";
+import { type Chats } from "./chats.js";
+import type { WorkspaceIdOptions, WorkspaceIdTarget } from "./tenant-workspaces.js";
+import type { CreateSessionRequest, 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;
+};
+/** 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. */
+export type SessionProxyCreateInput = {
+    initialMessage: string;
+    /** Browser retry key; replay is scoped to the acting user by the API. */
+    idempotencyKey?: string | undefined;
+};
+/** Which browser action is about to forward a user message or response. */
+export type SessionProxyMessageInput = {
+    /** Absent for `create`. */
+    sessionId?: string | undefined;
+    delivery: "create" | "send" | "steer" | "submit";
+};
+/** 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.
+     */
+    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, and human-input response.
+     * Return server-owned `modelContext` (messages 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). Defaults to true. */
+    files?: 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;
+    /**
+     * 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
+     * or draft (still limited by the workspace model catalog). When false those
+     * choices are removed from messages and draft saves. 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).
+     */
+    modelSelection?: boolean | undefined;
+    /** SSE heartbeat interval. Defaults to 15 seconds. */
+    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-RWKB6YZG.js";
+import "./chunk-UM4ZXXJR.js";
+import "./chunk-U6CV2SXO.js";
+import "./chunk-APXVSSSY.js";
+import "./chunk-YIKA2QT4.js";
+import "./chunk-V6GIY62B.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/site-browser-entry.d.ts

@@ -0,0 +1 @@
+export {};