@opengeni/sdk 1.0.2-canary.37191796234001 → 1.0.2

package/README.md

@@ -52,79 +52,96 @@ change allowances.
 
 ## Embed the conversation (default)
 
-The default product integration is the full OpenGeni conversation:
-`@opengeni/react`'s `SessionConversation` in the browser, backed by this SDK
-through a tenant/user-scoped same-origin proxy on your server.
-`createSessionProxyHandler` is that proxy, packaged:
+Embedding Opengeni is one backend route plus one component, and you only speak
+in your own ids. The browser renders `@opengeni/react`'s `OpenGeniChat` (or
+`SessionConversation`); your server mounts `createSessionProxyHandler`, a
+same-origin proxy that acts as your authenticated user:
 
 ```ts
-// Server: mount at /api/opengeni/* (see the framework adapters below).
-import { OpenGeniClient, createSessionProxyHandler } from "@opengeni/sdk";
+// lib/opengeni.ts (server only: the organization API key never reaches the browser)
+import { OpenGeni } from "@opengeni/sdk/chat";
 
-const og = new OpenGeniClient({
-  baseUrl: process.env.OPENGENI_API_BASE_URL!,
-  apiKey: process.env.OPENGENI_API_KEY!,
-});
+export const og = new OpenGeni({ apiKey: process.env.OPENGENI_API_KEY! });
+```
+
+```ts
+// app/api/opengeni/[...path]/route.ts (any web-standard host works; see the adapters below)
+import { createSessionProxyRoute } from "@opengeni/sdk/next";
+import { og } from "@/lib/opengeni";
 
-export const handler = createSessionProxyHandler(og, {
+export const dynamic = "force-dynamic";
+export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
   resolve: async (request) => {
-    const me = await authenticate(request); // your session/cookie check
+    const me = await authenticate(request); // your existing session check
     if (!me) return new Response("Unauthorized", { status: 401 });
-    return { workspaceId: me.openGeniWorkspaceId, user: me.userId, source: "acme-app" };
+    return { user: me.id, tenant: me.orgId }; // or { user: me.id }
   },
-  authorizeMutation: (request) => verifyCsrf(request), // your existing CSRF policy
-  // Optional. Omit to keep session creation purely server-side.
-  createSession: ({ initialMessage, idempotencyKey }) => ({
-    initialMessage,
-    idempotencyKey: idempotencyKey ?? crypto.randomUUID(),
-    tools: [{ kind: "mcp", id: "acme" }], // explicit, server-chosen tool selection
-    firstPartyMcpTools: [],
-  }),
+  createSession: (input) => input, // let the browser start chats
 });
 ```
 
 ```tsx
-// Browser: the unmodified SDK client, pointed at your mount.
-import { OpenGeniClient } from "@opengeni/sdk";
-import { OpenGeniChat, OpenGeniProvider } from "@opengeni/react";
+// app/assistant/assistant.tsx (browser): no provider, client, or workspace id.
+"use client";
+import { OpenGeniChat } from "@opengeni/react";
 import "@opengeni/react/compiled.css";
 
-const client = new OpenGeniClient({ baseUrl: "/api/opengeni" });
-<OpenGeniProvider client={client} workspaceId={workspaceId}>
-  {/* The user's chat list plus the conversation; or <SessionConversation sessionId={id} />. */}
-  <OpenGeniChat />
-</OpenGeniProvider>;
+export function Assistant() {
+  return <OpenGeniChat baseUrl="/api/opengeni" />; // chat list + conversation
+}
 ```
 
-The proxy and `@opengeni/sdk/chat` facade accept `chats`. The proxy defaults to
-`"private"`; the facade does too when a `user` is present. Without a user and with
-`chats` omitted, the facade keeps workspace visibility, session-only agent reach
-and Knowledge authoring off. Explicit `"private"` requires an authenticated user.
-Private chats use private visibility, session-only agent reach and personal
-Knowledge; `"shared"` uses workspace visibility, agent reach and Knowledge.
-The API wire values are `visibility: "private" | "workspace"`; stored visibility
-is `user_private | workspace_shared`. Explicit hook/create fields override defaults.
-
-For `"isolated"`, pass the facade and return `{ tenant, user }` from `resolve`.
-`og.workspaceIdFor({ tenant, user }, { isolation: "user" })` provisions a separate
-workspace and that user's external membership. It uses stable onboarding keys,
-so retries do not restore revoked access. Other modes need explicit onboarding.
-The standalone resolver is on the server-only `@opengeni/sdk/tenant-workspaces`
-subpath. Keep tenant and user values host-authenticated.
-
-Isolated members get only workspace read, session create/read/control (including
-sending messages), file upload/read, and `mcp_servers:attach` for host-provided
-per-session servers. No admin permissions are included. Pass `memberPermissions`
-to the `OpenGeni` constructor or `createWorkspaceIdResolver` options to replace
-that list, for example to disable file uploads or MCP attachment. The organization
-key must also permit each operation. This is initial onboarding, not a membership
-update: changing the option does not update existing grants or restore revoked access.
-Keep MCP URLs and credentials in the server's `createSession` hook; the browser
-cannot choose them through the proxy.
-An existing onboarding conflict returns the workspace address without retrying
-or changing the grant. The address is not authorization: later `asUser` calls
-still enforce current permissions. Existing isolated users need an explicit
-`updateExternalWorkspaceMember` to gain newly added permissions such as MCP attachment.
+`baseUrl` makes the component create the browser client for your mount and use
+the workspace the proxy resolved for the signed-in user (reported in the
+proxy's client config). One conversation alone is
+`<SessionConversation baseUrl="/api/opengeni" sessionId={id} />`. The
+`<OpenGeniProvider client={client} workspaceId={workspaceId}>` form keeps
+working, for example for several components or the headless hooks.
+
+What `resolve` returns decides the workspace:
+
+- `{ user, tenant }`: one workspace per tenant; chats are private per user by
+  default.
+- `{ user }`: one workspace per user. It stays single-user: the SDK adds its
+  owner once, and Opengeni never admits anyone else to it.
+- `{ user, workspaceId }`: bring your own workspace id.
+
+Workspaces are created on first use and cached per `OpenGeni` instance.
+`og.workspaceId({ tenant })` and `og.workspaceId({ user })` return the same ids
+the proxy uses. There is no onboarding step: the first request a user makes
+adds them to a tenant (or your own) workspace with conversation permissions
+(workspace read, session create/read/control, file upload/read, and attaching
+your per-session MCP servers; no admin). That needs an organization API key
+with `members:manage` (full access includes it) plus those permissions.
+Opengeni never changes an existing membership, so narrowing or widening one
+with `updateExternalWorkspaceMember` sticks. A user you remove from a tenant
+workspace is added again on their next request, because your product decides
+who its users are; stop resolving a user you no longer admit. A removal from a
+per-user workspace sticks. `organizationId` is optional:
+the facade reads it once from the key. Keep `user` and `tenant`
+host-authenticated, never from the request body or path.
+
+The proxy and facade accept `chats`. `"private"` (the default with a user)
+uses private visibility, session-only agent reach and personal Knowledge;
+`"shared"` uses workspace visibility, agent reach and Knowledge, so a tenant's
+users see each other's chats. Without a user and with `chats` omitted, the
+facade keeps workspace visibility, session-only agent reach and Knowledge
+authoring off. The API wire values are `visibility: "private" | "workspace"`;
+stored visibility is `user_private | workspace_shared`. Explicit hook/create
+fields override defaults. Keep MCP URLs and credentials in the server's
+`createSession` hook; the browser cannot choose them through the proxy.
+
+You can also pass a plain `OpenGeniClient` (organization key) instead of the
+facade; then `resolve` must return `{ user, workspaceId }`. The explicit
+membership APIs (`ensureWorkspace`, `addExternalWorkspaceMember`,
+`updateExternalWorkspaceMember`, `cancelExternalWorkspaceMemberGrant`) keep
+working for products that manage access themselves. Legacy
+`chats: "isolated"` with `{ tenant, user }` still provisions a separate
+workspace per user and tenant. Per-user workspaces add their owner with a
+stable onboarding key, so a retry never restores a revoked grant;
+`memberPermissions` replaces that owner's permissions on first onboarding
+only. The standalone resolver is on the server-only
+`@opengeni/sdk/tenant-workspaces` subpath.
 
 The facade also accepts `agent` (identity, capabilities, instructions, renderer)
 and defaults its renderer to `"markdown"`. Current servers always admit agent
@@ -260,12 +277,12 @@ still cannot send `mcpCredentialUpdates` itself. With `modelSelection: false`
 the proxy reports `modelSelection: false` in the client config, and
 `SessionConversation` hides its model picker.
 
-Onboard each user explicitly before their first request (see
-[External users](#external-users-asuser)); the proxy never grants membership.
-The conversation needs `workspace:read`, `sessions:read`, `sessions:control`,
-plus `sessions:create` when the user creates sessions and `files:upload` /
-`files:read` for attachments. Pass the facade from `@opengeni/sdk/chat` instead
-of a client to resolve `{ tenant, user }` through `ensureWorkspace`.
+Opengeni adds each user to the workspace on their first request (see
+[External users](#external-users-asuser)), with `workspace:read`,
+`sessions:create`, `sessions:read`, `sessions:control`, `files:upload`,
+`files:read`, and `mcp_servers:attach`. Pass the facade from `@opengeni/sdk/chat`
+instead of a client to resolve `{ tenant, user }` or `{ user }` to a workspace
+created on first use.
 
 ## Quick start
 
@@ -401,17 +418,34 @@ On a product backend, `client.asUser(externalId, { source? })` returns a separat
 client that sends the external actor assertion with the organization key. IDs
 are opaque and case-sensitive; the default source is `default`. Keep the key and
 this client server-side. Each request requires the intersection of the key's
-permissions and the user's explicit workspace membership. API-key rotation does
-not change the external identity.
+permissions and the user's workspace membership. API-key rotation does not
+change the external identity.
+
+Membership is automatic: when an `asUser` request reaches a shared workspace of
+the key's own organization and the user has no membership there, Opengeni adds
+one with conversation permissions (workspace read, session create/read/control,
+file upload/read, `mcp_servers:attach`) and continues the request. This needs
+the same authority as explicit onboarding: the key holds `members:manage` (or a
+legacy `workspace:admin`) and every one of those permissions, with the
+workspace in its scope; otherwise the request is a `403` as before. It never
+applies to linked native identities, Personal workspaces, SDK per-user
+workspaces (`opengeni-sdk:user-isolation:*` external source), other
+organizations, requests that need a permission outside those defaults, or any
+non-key caller, and it never changes an existing membership. The identity is
+re-checked as active under the same lock, and the grant writes the same
+receipt and lifecycle event as explicit onboarding, attributed to the key. A
+user removed from a shared workspace is added again on their next request; a
+suspended or offboarded identity stays refused.
 
 Use the service client—not an `asUser` client—to call
 `addExternalWorkspaceMember(workspaceId, { identity: { externalId, source? }, permissions })`
-for explicit onboarding. It requires `members:manage`, cannot grant more than
-the key permits, excludes Personal workspaces, and refuses to overwrite an
-existing membership with different permissions; change an existing member's permissions with the keyed
+to choose permissions up front. It requires `members:manage`, cannot grant more
+than the key permits, excludes Personal workspaces, and refuses to overwrite an
+existing membership with different permissions (`409`, also when automatic
+membership already created it); change an existing member's permissions with the keyed
 `updateExternalWorkspaceMember(organizationId, workspaceId, organizationMembershipId,
-{ operationId, permissions })`, which never tears down work. Ordinary `asUser` calls never
-restore removed workspace membership or reactivate disabled identities.
+{ operationId, permissions })`, which never tears down work. `asUser` calls never
+reactivate disabled identities.
 
 Service `removeWorkspaceMember` supports external members through the existing
 fenced workspace teardown. Account-wide `updateExternalIdentityMembership(
@@ -464,21 +498,13 @@ import { OpenGeni, createChatHandler } from "@opengeni/sdk/chat";
 
 const og = new OpenGeni({
   baseUrl: process.env.OPENGENI_API_BASE_URL!, // omitted = production https://app.opengeni.ai
-  apiKey: process.env.OPENGENI_API_KEY!,
-  organizationId: process.env.OPENGENI_ORGANIZATION_ID!,
+  apiKey: process.env.OPENGENI_API_KEY!, // the organization id is derived from the key
   source: "acme-app", // labels your product's tenants and users (default "app")
 });
 
-// Once per user, when your product admits them to the tenant. Chat requests
-// never grant workspace membership; without it the API answers 403.
-await og.client.addExternalWorkspaceMember(await og.workspaceId({ tenant: "acme" }), {
-  identity: { externalId: "u_42", source: og.source },
-  permissions: ["workspace:read", "sessions:create", "sessions:read", "sessions:control"],
-});
-
 const chat = await og.chat({
-  tenant: "acme", // one workspace per customer, created on first use
-  user: "u_42", // authenticated product user; onboard workspace membership first
+  tenant: "acme", // one workspace per customer, created on first use; omit for one per user
+  user: "u_42", // authenticated product user; added to the workspace on first use
   conversation: "c_9", // stable conversation id, independent of the acting user
   agentAccess: "session", // "session" (default) | "user" | "workspace"
   memory: "user", // "user" | "workspace" | false; session-only agent reach defaults to false
@@ -521,8 +547,8 @@ export const POST = handler; // send a message, or answer a pending request at .
 Conversation IDs do not change with the acting user. Authorized collaborators
 can use the same session; private visibility prevents access by other users.
 Use `chatBySessionId` for existing and legacy user-namespaced conversations.
-User mode requires explicit workspace membership and never restores removed
-membership automatically. Without a `user`, the host must name the conversation
+A user is added to the workspace on their first request (see
+[External users](#external-users-asuser)). Without a `user`, the host must name the conversation
 from `resolve`. The Vercel and OpenAI adapters send only the latest user
 message; the earlier messages in that request are imported once, as context on
 the first message of a conversation, after which OpenGeni owns the history.
@@ -703,7 +729,7 @@ const og = new OpenGeniClient({
   baseUrl: process.env.OPENGENI_API_BASE_URL!,
   apiKey: process.env.OPENGENI_API_KEY!,
 });
-// Existing tenant mapping + explicitly onboarded original creator.
+// Existing tenant mapping; the original creator is admitted on first use.
 const actor = og.asUser(originalExternalUserId, { source });
 const imported = await importArchivedSession(actor, workspaceId, {
   importId: "embedded:thread-42", // Stable; persist the exact request before sending.

package/dist/adapters/next.js

@@ -1,11 +1,11 @@
 import {
   createSessionProxyHandler
-} from "../chunk-ANKRFHYG.js";
+} from "../chunk-RWKB6YZG.js";
 import "../chunk-UM4ZXXJR.js";
-import "../chunk-P7BAOGEM.js";
-import "../chunk-4UPT3FIF.js";
-import "../chunk-LF2ONL44.js";
-import "../chunk-U54UBB7D.js";
+import "../chunk-U6CV2SXO.js";
+import "../chunk-APXVSSSY.js";
+import "../chunk-YIKA2QT4.js";
+import "../chunk-V6GIY62B.js";
 
 // src/adapters/next.ts
 function toNextRouteHandlers(handler) {

package/dist/artifacts.js

@@ -1,12 +1,12 @@
 import {
   OpenGeniClient
-} from "./chunk-OP3VOVII.js";
-import "./chunk-DSVI5QBQ.js";
-import "./chunk-6TEGEI4E.js";
-import "./chunk-4UPT3FIF.js";
-import "./chunk-LF2ONL44.js";
-import "./chunk-L2JTM5ZK.js";
-import "./chunk-U54UBB7D.js";
+} from "./chunk-AH5D5Q5V.js";
+import "./chunk-HMGADJGZ.js";
+import "./chunk-FG3OO5LM.js";
+import "./chunk-APXVSSSY.js";
+import "./chunk-YIKA2QT4.js";
+import "./chunk-NC57YMUO.js";
+import "./chunk-V6GIY62B.js";
 export {
   OpenGeniClient
 };

package/dist/browser.js

@@ -5,16 +5,16 @@ import {
   OpenGeniToolCallError,
   OpenGeniToolReapprovalRequiredError,
   OpenGeniToolsClient
-} from "./chunk-D37KNKO6.js";
+} from "./chunk-4SMEOV3P.js";
 import {
   OpenGeniClient
-} from "./chunk-6TEGEI4E.js";
-import "./chunk-4UPT3FIF.js";
+} from "./chunk-FG3OO5LM.js";
+import "./chunk-APXVSSSY.js";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION
-} from "./chunk-LF2ONL44.js";
-import "./chunk-L2JTM5ZK.js";
+} from "./chunk-YIKA2QT4.js";
+import "./chunk-NC57YMUO.js";
 import {
   OpenGeniAllowanceExhaustedError,
   OpenGeniApiContractMismatchError,
@@ -25,7 +25,7 @@ import {
   OpenGeniStreamError,
   formatErrorMessage,
   isRetryableStreamError
-} from "./chunk-U54UBB7D.js";
+} from "./chunk-V6GIY62B.js";
 export {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,

package/dist/chat/index.d.ts

@@ -1,7 +1,7 @@
 export type { Chats } from "../chats.js";
 export { OpenGeniSetupError } from "../errors.js";
 export { Chat, DEFAULT_CHAT_SOURCE, DEFAULT_OPENGENI_BASE_URL, IMPORTED_HISTORY_MAX_CHARS, OpenGeni, formatImportedHistory, } from "./opengeni.js";
-export { OpenGeniChatError, type ChatAgentAccess, type ChatChunk, type ChatImportedMessage, type ChatMemory, type ChatMessage, type ChatOptions, type ChatPending, type ChatReply, type ChatReplyStatus, type ChatRespondInput, type ChatSendOptions, type ChatSessionListOptions, type ChatSnapshot, type ChatTarget, type ChatToolStatus, type OpenGeniOptions, } from "./types.js";
+export { OpenGeniChatError, type ChatAgentAccess, type ChatChunk, type ChatImportedMessage, type ChatMemory, type ChatMessage, type ChatOptions, type ChatPending, type ChatReply, type ChatReplyStatus, type ChatRespondInput, type ChatSendOptions, type ChatSessionListOptions, type ChatSnapshot, type ChatTarget, type WorkspaceTarget, type ChatToolStatus, type OpenGeniOptions, } from "./types.js";
 export { CHAT_SESSION_NAMESPACE, chatIdempotencyKey, chatIdentityName, chatSessionId, uuidV5, type ChatUserLabel, } from "./ids.js";
 export { ChatTurnFold, approvalPending, humanInputPending, type ChatFoldStep, type ChatTurnTerminal, } from "./fold.js";
 export { CHAT_CONVERSATION_HEADER, CHAT_FORMAT_HEADER, chatChunksToSseBlocks, chatChunksToSseResponse, chatChunksToSseStream, createChatHandler, handleNativeChatRequest, handleNativeHistoryRequest, handleNativeRespondRequest, parseChatChunkStream, respondInputFromBody, type ChatHandlerFormat, type ChatHandlerOptions, type ChatResolution, type ChatResolve, } from "./handler.js";

package/dist/chat/index.js

@@ -6,27 +6,27 @@ import {
   createWorkspaceIdResolver,
   isUuid,
   uuidV5
-} from "../chunk-SRWDF5FG.js";
+} from "../chunk-LY2K6ELJ.js";
 import {
   EMPTY_FINAL_REPLY_NOTICE,
   OpenGeniEmbeddingClient,
   turnCompletedWithEmptyFinalReply
-} from "../chunk-EBDZD5XW.js";
-import "../chunk-OP3VOVII.js";
-import "../chunk-DSVI5QBQ.js";
+} from "../chunk-MOTJYIYL.js";
+import "../chunk-AH5D5Q5V.js";
+import "../chunk-HMGADJGZ.js";
 import {
   chatDefaults
 } from "../chunk-UM4ZXXJR.js";
-import "../chunk-6TEGEI4E.js";
+import "../chunk-FG3OO5LM.js";
 import {
   parseSseStream
-} from "../chunk-4UPT3FIF.js";
-import "../chunk-LF2ONL44.js";
-import "../chunk-L2JTM5ZK.js";
+} from "../chunk-APXVSSSY.js";
+import "../chunk-YIKA2QT4.js";
+import "../chunk-NC57YMUO.js";
 import {
   OpenGeniApiError,
   OpenGeniSetupError
-} from "../chunk-U54UBB7D.js";
+} from "../chunk-V6GIY62B.js";
 
 // src/chat/types.ts
 var OpenGeniChatError = class extends Error {
@@ -378,44 +378,116 @@ var IMPORTED_HISTORY_HEADER = "Earlier conversation imported from the product, o
 var IMPORTED_HISTORY_ROLES = /* @__PURE__ */ new Set(["user", "assistant", "system"]);
 var OpenGeni = class {
   client;
+  /**
+   * The organization id: the one passed to the constructor, else the one
+   * derived from the API key once {@link resolveOrganizationId} (or any
+   * workspace lookup) has run. An empty string before that; prefer
+   * `await og.resolveOrganizationId()`.
+   */
   organizationId;
   source;
   sessions;
   resolveWorkspaceId;
   implicitAgentAdmission;
+  pendingOrganizationId;
   constructor(options) {
-    if (!options.apiKey) throw new TypeError("OpenGeni requires an apiKey.");
-    if (!options.organizationId) throw new TypeError("OpenGeni requires an organizationId.");
+    if (!options.apiKey) throw new TypeError("Opengeni requires an apiKey.");
     this.client = new OpenGeniEmbeddingClient({
       baseUrl: options.baseUrl ?? DEFAULT_OPENGENI_BASE_URL,
       apiKey: options.apiKey,
       ...options.fetch ? { fetch: options.fetch } : {}
     });
-    this.organizationId = options.organizationId;
+    this.organizationId = options.organizationId ?? "";
     this.source = options.source ?? DEFAULT_CHAT_SOURCE;
     this.resolveWorkspaceId = createWorkspaceIdResolver(this.client, {
-      organizationId: this.organizationId,
+      organizationId: () => this.resolveOrganizationId(),
       source: this.source,
       workspaceName: options.workspaceName,
       memberPermissions: options.memberPermissions
     });
     this.sessions = { list: (listOptions) => this.listSessions(listOptions) };
   }
-  /** The workspace id for a tenant (created on first use, cached per instance) or an explicit id. */
+  /**
+   * The organization that owns every workspace this facade creates. Uses the
+   * constructor's `organizationId`, else reads it once from the API key
+   * (`GET /v1/access/me`) and caches it.
+   */
+  async resolveOrganizationId() {
+    if (this.organizationId) return this.organizationId;
+    if (!this.pendingOrganizationId) {
+      const pending = this.client.getAccessContext().then((access) => {
+        const credential = access.credential;
+        if (credential && credential.kind !== "organization_api_key") {
+          throw new TypeError(
+            "OpenGeni needs an organization API key to create workspaces; this is a workspace key."
+          );
+        }
+        const organizationId = credential?.accountId ?? access.defaultAccountId;
+        if (!organizationId) {
+          throw new TypeError(
+            "Could not derive the organization from this API key. Pass organizationId."
+          );
+        }
+        this.organizationId = organizationId;
+        return organizationId;
+      });
+      pending.catch(() => {
+        if (this.pendingOrganizationId === pending) this.pendingOrganizationId = void 0;
+      });
+      this.pendingOrganizationId = pending;
+    }
+    return await this.pendingOrganizationId;
+  }
+  /**
+   * Translate your own ids to the Opengeni workspace id, creating the
+   * workspace on first use (cached per instance):
+   * `{ tenant }` is one workspace per tenant, `{ user }` (no tenant) is one
+   * workspace per user, and `{ workspaceId }` is returned as is. Opengeni adds
+   * a tenant workspace's users on their first request; a per-user workspace
+   * gets its one owner from the SDK and admits nobody else.
+   */
   async workspaceId(target) {
+    if (target.workspaceId === "" || target.tenant === "") {
+      throw new TypeError("tenant and workspaceId must be non-empty ids.");
+    }
     if (target.workspaceId) return target.workspaceId;
-    const tenant = target.tenant;
-    if (!tenant) throw new TypeError("Pass either tenant or workspaceId.");
-    return await this.workspaceIdFor({ tenant }, { isolation: "tenant" });
+    if (target.tenant) {
+      return await this.workspaceIdFor({ tenant: target.tenant }, { isolation: "tenant" });
+    }
+    if ("tenant" in target || "workspaceId" in target) {
+      throw new TypeError(
+        "tenant or workspaceId is undefined. Pass a non-empty id, or omit the key for one workspace per user."
+      );
+    }
+    const user = "user" in target ? target.user : void 0;
+    if (user) {
+      return await this.workspaceIdFor({ user }, { isolation: "user" });
+    }
+    throw new TypeError("Pass tenant, user, or workspaceId.");
   }
-  /** Resolve a tenant workspace, or provision its separate user workspace and external member. */
+  /**
+   * Resolve a tenant workspace or a user's own workspace (user isolation, per
+   * tenant when one is given). A user's own workspace is provisioned with that
+   * user as its only explicit member.
+   */
   async workspaceIdFor(target, options) {
     return await this.resolveWorkspaceId(target, options);
   }
+  /** `chats: "isolated"` keeps its tenant-plus-user workspace; a user alone gets their own. */
+  async isolatedWorkspaceId(target) {
+    if (target.workspaceId) {
+      throw new TypeError('chats: "isolated" requires a tenant or user, not a workspaceId.');
+    }
+    return await this.workspaceIdFor(
+      { tenant: target.tenant, user: target.user },
+      { isolation: "user" }
+    );
+  }
   /**
    * Address one conversation; the session is created lazily on the first send.
-   * Identity selects authority, not the conversation address. Workspace
-   * membership must be provisioned by the host's explicit onboarding flow.
+   * Identity selects authority, not the conversation address. The workspace
+   * is the tenant's, the user's own (user only), or the explicit id; Opengeni
+   * adds the user to it on their first request.
    * Legacy user-namespaced conversations remain accessible by their session ID.
    */
   async chat(options) {
@@ -442,10 +514,7 @@ var OpenGeni = class {
       );
     }
     const client = options.user ? this.client.asUser(options.user, { source: this.source }) : this.client;
-    const workspaceId = options.chats === "isolated" ? await this.workspaceIdFor(
-      { tenant: options.tenant ?? "", user: options.user },
-      { isolation: "user" }
-    ) : await this.workspaceId(options);
+    const workspaceId = options.chats === "isolated" ? await this.isolatedWorkspaceId(options) : await this.workspaceId(options);
     const sessionId = options.sessionId ?? await chatSessionId(workspaceId, options.conversation);
     const session = await this.findSession(client, workspaceId, sessionId);
     const buildCreate = (text, send) => {
@@ -537,10 +606,7 @@ var OpenGeni = class {
     }
   }
   async listSessions(options) {
-    const workspaceId = options.chats === "isolated" ? await this.workspaceIdFor(
-      { tenant: options.tenant ?? "", user: options.user },
-      { isolation: "user" }
-    ) : await this.workspaceId(options);
+    const workspaceId = options.chats === "isolated" ? await this.isolatedWorkspaceId(options) : await this.workspaceId(options);
     const client = options.user ? this.client.asUser(options.user, { source: this.source }) : this.client;
     return await client.requestJson(
       "GET",