@opengeni/sdk 3.1.0 → 3.1.2

package/README.md

@@ -1,17 +1,343 @@
 # @opengeni/sdk
 
-Framework-agnostic TypeScript SDK for the OpenGeni public API: a typed client,
+Framework-agnostic TypeScript SDK for the Opengeni public API: a typed client,
 session lifecycle, and the streaming core — SSE event streaming with automatic
 reconnect, resume-by-sequence, gap backfill, and duplicate suppression — plus
 helpers for proxying the stream through your own API.
 
-Zero runtime dependencies. Needs only WHATWG `fetch` and streams, so it runs in
-Node 18+, Bun, Deno, browsers, and edge runtimes.
+For the complete product boundary—organization API keys, organization
+workspaces, Personal-workspace exclusion, tenant mapping, and external Skill
+ownership—start with the canonical
+[product integration guide](../../docs/product-integration.md).
+
+Runtime dependencies are the published `@opengeni/contracts` wire schemas (which
+bring Zod) and `@opengeni/connect`; nothing else. It needs only WHATWG `fetch`
+and streams, so it runs in Node 18+, Bun, Deno, browsers, and edge runtimes.
+The package is ESM-only (no `require` entry): use `import`, or `await import()`
+from CommonJS.
+
+Always pass `baseUrl` (for example `process.env.OPENGENI_API_BASE_URL`): the
+chat facade defaults to production `https://app.opengeni.ai`, so omitting it
+against a staging or self-hosted deployment silently talks to production.
+
+Browser clients may call the public API from any origin with an explicitly safe
+bearer design, but an organization API key belongs on the product server.
+Browser cookies are accepted cross-origin only from operator-configured trusted
+origins; arbitrary embedding origins never receive credentialed CORS responses.
+
+## Task usage limits
+
+`createSession(workspaceId, { initialMessage, usageLimitMicros })` sets an
+optional API-equivalent model-usage limit on a new root task;
+`getSessionUsageLimit` and `setSessionUsageLimit` (compare-and-set on
+`expectedVersion`, idempotent on `operationId`, `limitMicros: null` clears)
+read and change it. Both writes verify the server's echo and throw when a
+server that predates usage limits would otherwise run the task unlimited. A
+refused message raises `OpenGeniSessionUsageLimitReachedError` (HTTP 402
+`session_usage_limit_reached`), never the allowance error. The browser-safe
+`@opengeni/sdk/session-usage-limits` subpath exports the free functions, the
+refusal parser and neutral wording. The session proxy never forwards limits
+from a browser; set them from your server. See
+[task usage limits](../../docs/session-usage-limits.md).
+
+## Allowance lifecycle recovery
+
+`getWorkspaceAllowance(workspaceId)` still returns nullable configuration.
+Use `getWorkspaceAllowanceState(workspaceId)` when you also need the lifecycle
+version: `{ version: 0, config: null }` means never configured, while a positive
+version with null configuration means cleared. Recreation uses that exact
+version as `expectedVersion`.
+
+`clearWorkspaceAllowance(workspaceId, { expectedVersion, operationId })` returns
+`{ version }`. The optional operation ID makes a lost response recoverable:
+reuse the same actor, operation ID and exact request. Replay rechecks current
+authority and returns 409 after any later allowance lifecycle change. On 409,
+read the current state and decide whether a new operation is intended; never
+guess a CAS version. The SDK does not automatically retry mutations.
+
+The same reads and administration are free functions on the
+`@opengeni/sdk/usage-allowances` subpath for browser code that only has the
+narrow `OpenGeniBrowserClient` (`getMyUsage(client, workspaceId)`,
+`getAllUsage`, `setMemberAllowance`, ...); they call the same routes as the root methods.
+
+State reads require the same budget-read authority as configuration reads.
+Full usage additionally requires target workspace access; organization budget
+authority alone does not expose the member roster. Agents cannot read or
+change allowances.
+
+## Embed the conversation (default)
+
+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:
 
-Browser clients may call the public API from any origin with an API key or
-other bearer credential. Browser cookies are accepted cross-origin only from
-operator-configured trusted origins; arbitrary embedding origins never receive
-credentialed CORS responses.
+```ts
+// lib/opengeni.ts (server only: the organization API key never reaches the browser)
+import { Opengeni } from "@opengeni/sdk/chat";
+
+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 dynamic = "force-dynamic";
+export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, {
+  resolve: async (request) => {
+    const me = await authenticate(request); // your existing session check
+    if (!me) return new Response("Unauthorized", { status: 401 });
+    return { user: me.id, tenant: me.orgId }; // or { user: me.id }
+  },
+  createSession: (input) => input, // let the browser start chats
+});
+```
+
+```tsx
+// app/assistant/assistant.tsx (browser): no provider, client, or workspace id.
+"use client";
+import { OpenGeniChat } from "@opengeni/react";
+import "@opengeni/react/compiled.css";
+
+export function Assistant() {
+  return <OpenGeniChat baseUrl="/api/opengeni" />; // chat list + conversation
+}
+```
+
+`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
+configuration. For older servers that still gate it, only an implicit renderer
+retries once without `agent` on `422 agent_config_not_enabled`, and that refusal
+is cached per facade instance. Explicit agent settings are never stripped: the
+422 names `OPENGENI_AGENT_CONFIG_ADMISSION_ENABLED` for that older server's
+operator. The private default with a user now turns personal Knowledge
+on; pass `memory: false` to keep authoring off.
+Missing organization private-session enablement raises `OpenGeniSetupError`,
+with owner/admin API, SDK and web-app instructions; the proxy preserves that
+actionable error for browser clients.
+
+Framework adapters are thin wrappers over the same web-standard handler (they
+also accept `createChatHandler` or any `(Request) => Promise<Response>`):
+
+```ts
+// Next.js App Router: app/api/opengeni/[...path]/route.ts
+import { createSessionProxyRoute } from "@opengeni/sdk/next";
+export const dynamic = "force-dynamic";
+export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, { resolve });
+
+// Express / Connect / node:http (mount before body parsers, or they are re-serialized)
+import { toNodeMiddleware } from "@opengeni/sdk/express";
+app.use("/api/opengeni", toNodeMiddleware(handler));
+
+// Hono
+import { toHonoHandler } from "@opengeni/sdk/hono";
+app.all("/api/opengeni/*", toHonoHandler(handler));
+```
+
+The Next adapter passes the full URL, including any `basePath`; the Node
+middleware rebuilds it from `originalUrl`, streams bodies and SSE, and aborts
+the request when the client disconnects.
+
+The chat list (`SessionList` / `OpenGeniChat`) uses `listSessionPage`. By
+default (`sessionList: "mine"`) the proxy adds a creator filter for the
+resolved user server-side, so each user sees only the chats they started;
+`sessionList: "visible"` lists every chat Opengeni lets the user read in the
+workspace, and `false` disables listing. Archive and restore go through
+`updateSessionArchive` unless `archive: false`. That personal archive only hides
+a chat from one member's list. The deployment's idle-session archive is separate:
+it makes long-idle sessions read-only and is reported on `session.retention`.
+Pass `keepLive: true` to `createSession`, or call
+`updateSessionRetention(workspaceId, sessionId, { keepLive: true })`, to keep a
+persistent agent's session out of it. A "New chat" in `OpenGeniChat`
+sends `{ initialMessage, idempotencyKey }` plus any attached file `resources`
+and, unless `modelSelection: false`, the user's explicit model choices, so it
+needs the `createSession` hook. The hook sees them as input; the proxy adds the
+files and applies those choices to the request the hook returns. Voice input
+(`POST .../transcriptions`) is forwarded as the resolved user unless
+`voiceInput: false`. The client config the proxy serves reports what it can do:
+`sessionCreation` (a `createSession` hook exists), `archive`, and `artifacts`
+(`false` unless `artifacts: true`). The stock UI hides "New chat" and
+"Archive" when they are off, shows Site previews as unavailable without a
+request, and shows the composer microphone only when `voiceInput.available`.
+
+Composer uploads are refused for anonymous visitors: return `visitor: true`
+from `resolve` for a user your product has not signed in (for example a
+website visitor keyed by a cookie), and the proxy reports file uploads off and
+refuses the upload routes unless `visitorUploads: true`. Agent-produced media
+still loads under `files`.
+
+Live voice (speech-to-speech) is forwarded the same way unless
+`realtimeVoice: false`. The stock conversation shows its voice button only when
+you opt in, with `realtimeVoice: true` here (reported in the client config) or
+the component's `realtimeVoice` prop. The proxy forwards the workspace's voice model catalog and the call routes
+under `.../sessions/{id}/realtime` (start, provider connect, heartbeat,
+activate, transcript sync, end). Opengeni still checks the user's
+`sessions:control` permission, binds the call to that user and browser, runs
+spoken requests as steers of the same chat, and meters deployment-funded voice
+against your credits. `authorizeSession` runs on every call route, and
+`beforeForwardMessage` sees `delivery: "realtime"` when a call starts (refuse
+it, or return `mcpCredentialUpdates`; the proxy also refreshes the `toolServer`
+token) and before transcripts and spoken requests are saved (refuse them, or add
+`modelContext`, which must be the same when a request is retried).
+
+`listSessionPage` includes personal pinned details by default. A caller with a
+separate `pinsOnly: true` read can pass `includePinned: false` on ordinary pages
+to avoid repeatedly loading those details. Ordinary pages still exclude pinned
+rows; `pinsOnly: true` and `includePinned: false` cannot be combined. Older API
+versions may ignore `includePinned` and return the default pin projection.
+
+For navigation lists, `listSessionSummaryPage` uses the same filters, ordering,
+pin rules and cursors, returning `SessionListEntry` records. Entries include
+display/rename titles, creator, lifecycle, personal state, hierarchy counts and
+the model and reasoning effort shown with a row; prompts and the rest of the
+execution configuration remain on `getSession`. Older APIs return
+full pages that the SDK projects locally. Unknown filters/cursors still fail
+explicitly rather than returning an unfiltered result.
+
+Every request calls `resolve`, then runs through `asUser(user, { source })`
+(there is no service-authority fallback) against exactly the resolved
+workspace. Only the native routes `OpenGeniProvider` and the conversation use
+are served: client config; workspace read, model catalog, live control stream,
+and workspace Resume; session read/rename, events (list and SSE with
+`Last-Event-ID` resume), send/steer/approval/human-input, queue, composer
+draft, pause/resume, and the session goal (read; pause/resume, forwarding only
+`{ status: "paused" | "active" }`; and clear, the proxy's only `DELETE`); and, unless `files: false`, attachment upload and download
+URLs plus the media the session produced (generated images and video,
+published files, and browser or computer screenshots). Workspace-level
+artifact reads (`artifacts/:id/content` with `Range`, `artifacts/:id/playback-source`)
+must name their session in `x-opengeni-session-id`; the proxy runs
+`authorizeSession` and forwards only an artifact Opengeni proves that session
+produced. Every other route or method is a 404 (cancel and workspace Pause are
+refused); unknown query parameters on served reads pass through. Browser session creation is disabled
+unless you supply `createSession`; the browser may then send only
+`initialMessage` and `idempotencyKey`, and your hook returns the full request
+(tools, MCP servers, Skills, instructions, model policy). Message bodies are
+capped by `maxBodyBytes` (1 MiB), cannot rotate MCP credentials or attach
+anything but files, and `modelSelection: false` strips per-message model
+choices. `authorizeSession(sessionId, context)` adds a product-level session
+check on top of Opengeni's own membership and visibility checks. Without
+`authorizeMutation`, only cross-site (`Sec-Fetch-Site`) mutations are refused,
+so cookie-authenticated hosts should pass their CSRF check.
+
+### Your own tools, as the signed-in user
+
+`toolServer` attaches your product's MCP endpoint to every session the
+`createSession` hook creates, with a short-lived token for the user `resolve`
+authenticated. The proxy refreshes it on every send, steer, submit, approval,
+and human-input answer. Your endpoint, built with any MCP library, verifies it:
+
+```ts
+createSessionProxyHandler(og, {
+  resolve,
+  createSession,
+  toolServer: {
+    url: "https://app.example.com/api/mcp", // public HTTPS (tunnel locally)
+    approvals: { ask: ["rename_post"] }, // the user approves each call first
+  },
+});
+
+// In the MCP route (Web Request, or an Express/Node request):
+import { ToolRequestError, verifyToolRequest } from "@opengeni/sdk/tool-auth";
+const { user, tenant, workspaceId } = await verifyToolRequest(request); // or ToolRequestError (401)
+```
+
+Scope every tool to the verified `user` and `tenant`; never trust ids the model
+sends; list write tools in `approvals.ask`. Tools act as the chat's creator, also
+in shared chats. Members need `mcp_servers:attach`. Tokens are HS256 JWTs signed
+with a key derived from `OPENGENI_API_KEY` (or the same `secret` on both sides),
+bound to the full tool URL by `aud` (set `OPENGENI_TOOL_SERVER_URL` to configure
+both sides at once), and valid for `ttlSeconds` (default 24 hours). Non-Node
+verifiers use the hex key from `deriveToolTokenKey()`, never the organization key;
+the format is documented in `src/tool-auth.ts`. See
+`examples/tool-server` for a runnable Express version.
+
+`beforeForwardMessage(message, context)` runs before every forwarded user
+message (send, steer, composer submit, and a browser-started create) and may
+return server-owned additions, or a `Response` to refuse the message:
+
+```ts
+createSessionProxyHandler(og, {
+  resolve,
+  beforeForwardMessage: async ({ sessionId, delivery }, { user }) => ({
+    // Model-visible, placed before any context the browser sent.
+    modelContext: `Page ${currentPage(user)} · ${timeZone(user)} · ${today()}`,
+    // Header-only rotation of MCP servers already attached to the session,
+    // applied atomically as the message is accepted (ignored on create).
+    mcpCredentialUpdates: [
+      { id: "acme", headers: { Authorization: `Bearer ${await mintUserToken(user)}` } },
+    ],
+  }),
+});
+```
+
+This is the per-user tool token pattern: create the session with
+`mcpServers: [{ id: "acme", url, headers }]` (and `tools: [{ kind: "mcp", id:
+"acme" }]`, which the acting user needs `mcp_servers:attach` to attach), then
+hand the MCP server a fresh short-lived bearer on every message. The browser
+still cannot send `mcpCredentialUpdates` itself. With `modelSelection: false`
+the proxy reports `modelSelection: false` in the client config, and
+`SessionConversation` hides its model picker.
+
+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
 
@@ -19,7 +345,7 @@ credentialed CORS responses.
 import { OpenGeniClient } from "@opengeni/sdk";
 
 const client = new OpenGeniClient({
-  baseUrl: "https://api.example.com",
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
   apiKey: process.env.OPENGENI_API_KEY!,
 });
 
@@ -37,6 +363,95 @@ for await (const event of client.streamEvents(workspaceId, session.id)) {
 }
 ```
 
+## Organization-backed product setup
+
+A multi-tenant product should hold one organization API key on its backend and
+idempotently map each product tenant to an Opengeni organization workspace. The
+wire kind for an organization workspace is `"shared"`; Personal workspaces are
+excluded.
+
+```ts
+const client = new OpenGeniClient({
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
+  apiKey: process.env.OPENGENI_API_KEY!,
+});
+
+const organizationId = process.env.OPENGENI_ORGANIZATION_ID!;
+const { workspace, created } = await client.ensureWorkspace({
+  accountId: organizationId,
+  externalSource: "acme-product",
+  externalId: tenant.id,
+  name: tenant.displayName,
+});
+
+if (workspace.kind !== "shared") {
+  throw new Error("Product integrations require an organization workspace");
+}
+```
+
+The response is `{ workspace, created }`. Replays return the original nested
+workspace with `created: false`. For an organization key, `getAccessContext()`
+does not enumerate every workspace grant; call `listWorkspaces()` for the
+organization-workspace inventory allowed by the key's live scope.
+
+Organization key administration uses `listOrganizationApiKeys`,
+`getOrganizationApiKey`, `createOrganizationApiKey`, `updateOrganizationApiKey`,
+and `deleteOrganizationApiKey`. GET detail and PATCH return the raw `ApiKey`;
+creation returns `{ apiKey, token }`. The key token from a
+create response is shown once and must be stored in the backend's secret
+manager. `createOrganizationApiKey(organizationId, { name, access: "read" })`
+mints a read-only master key: it inventories shared workspaces and reads their
+sessions, events, and files, but cannot create sessions, send messages, or mint
+keys. This legacy `access: "read"` tier is distinct from the broader explicit
+`read_only` preset, which includes every read/list/view/search permission
+except the secret-value read `secrets:read`.
+
+Create or edit with `policy: { preset, permissions, workspaceScope }` for exact
+grants. `OrganizationAccessPreset` is `"read_only" | "full" | "custom"`;
+the label never adds permissions and the server recomputes it from the selected
+set. Explicit `full` selects every canonical non-deprecated permission; `custom`
+has no implicit grants or scope. Even `workspace:admin` grants no wildcard under
+an explicit policy. Scope is `{ kind: "all" }` (current and future shared
+workspaces) or `{ kind: "selected", workspaceIds }` (up to 500 unique same-org
+shared-workspace IDs; empty reaches none). Personal workspaces are always excluded.
+
+`updateOrganizationApiKey(organizationId, apiKeyId, { name?, description?, policy? })`
+requires at least one change; `description: null` clears it. Metadata-only edits
+preserve legacy stored permissions and wildcard semantics. A policy edit replaces
+the policy, transitions legacy keys to explicit semantics, and applies narrowing
+on the next request without rotating the token. Omitting policy at creation
+retains legacy `access`/`preset` inputs and the full legacy default.
+See [the canonical policy guide](../../docs/product-integration.md#explicit-organization-key-policies).
+
+Keys with session-read authority can call
+`listOrganizationSessions(organizationId, { limit, cursor, scopeSubjectId, status })`
+for one page of sessions across authorized shared workspaces (each row carries its
+`workspaceId`; private sessions and Personal workspaces never appear), or
+`iterateOrganizationSessions` to follow `nextCursor` to the end.
+
+The external backend also owns its Skill catalog. Load the selected definitions
+and pass them inline in `CreateSessionRequest.skills` for each product-created
+session. There is no organization-wide Skill registry or Skill inheritance in
+this integration contract. See the canonical guide for the complete route map,
+security boundary, and delivery checklist.
+
+Installed Skills can be workspace-managed or marked `session_selected`.
+Session-selected guidance is exposed to no agent
+until `createSession` names the reviewed immutable component in
+`installedSkillIds`. Opengeni copies that exact artifact into the new session,
+so omitting the field from customer-facing creates is a real contamination
+boundary rather than a prompt convention.
+The ordered selection is part of keyed-create identity: reusing an
+`idempotencyKey` with a different selection returns a conflict instead of the
+session configured by the earlier request.
+
+For session lists, `deriveSessionDisplayTitle(session)` returns the durable
+agent/user title when available. While the automatic title is still pending, it
+shows the first short, sensitive-safe line of the opening prompt, skipping an
+unsafe pasted URL or identifier when later safe text exists. If no safe line is
+available, a short session reference keeps rows distinguishable. The display
+automatically yields to the later `session.title_set` value.
+
 Browser consoles that do not need operator-only surfaces can import
 `OpenGeniBrowserClient` from `@opengeni/sdk/browser`. Document authority migration
 and Default-collection backfill methods stay available on the backward-compatible
@@ -47,11 +462,200 @@ root and `@opengeni/sdk/core` clients, or through the focused
 import { OpenGeniDocumentAuthorityClient } from "@opengeni/sdk/document-authority";
 
 const operatorClient = new OpenGeniDocumentAuthorityClient({
-  baseUrl: "https://api.example.com",
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
   apiKey: process.env.OPENGENI_API_KEY!,
 });
 ```
 
+## External users (`asUser`)
+
+On a product backend, `client.asUser(externalId, { source? })` returns a separate
+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 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 })`
+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. `asUser` calls never
+reactivate disabled identities.
+
+Service `removeWorkspaceMember` supports external members through the existing
+fenced workspace teardown. Account-wide `updateExternalIdentityMembership(
+organizationId, organizationMembershipId, { kind, expectedAuthorizationRevision,
+operationId, reason? })` requires explicit `account:admin` and supports suspend,
+reactivate, and offboard. The membership ID is returned by onboarding; its initial
+authorization revision is 1. Retain the returned revision for subsequent changes.
+Reactivation restores admission, not revoked memberships or work. Offboarding
+follows existing retention policy and cannot be reactivated through this API.
+Native-user targets and `asUser` calls are rejected by this service endpoint.
+
+An `asUser` client can discover/access its own provisioned Personal workspace
+under the key's permission ceiling. Core private session operations retain
+organization readiness/settings and explicit sharing acknowledgments; service
+clients gain no Personal-workspace fallback.
+
+Optional native-account delegation uses `beginIdentityLink`, authenticated native
+`previewIdentityLink`/`confirmIdentityLink`, and explicit server-side
+`asLinkedUser(externalId, { source?, linkId, expectedLinkRevision })`. Confirmation
+requires the actual native login plus the one-time host challenge; an organization
+key cannot confirm for the native user. `listIdentityLinks(workspaceId, cursor?)`
+returns only the effective participant's links in that organization (50 per page).
+`revokeIdentityLink` requires the observed revision. Linking never changes ordinary
+`asUser`, merges histories or transfers credentials. Link-dependent accepted work
+retains revocation checks across schedules and children. Short-lived inline MCP
+credentials remain supported, and durable renewal stays opt-in.
+
+Connect accepts an optional `installationTarget: { instanceKey, displayName,
+expectedInstanceVersion? }`. Keep the exact observed version for an existing named
+account. Setup freezes the target through callback and operation review; omitting
+it creates an independent named account instead of overwriting a default instance.
+
+## Chat facade fallback (`@opengeni/sdk/chat`)
+
+Use this only when your product already has its own chat UI speaking Vercel
+`useChat` or an OpenAI-shaped protocol and you want a compatible drop-in
+backend, or for server-side bots (`og.chat(...).send()`). It is a text-only
+projection: tool outputs are dropped (the Vercel adapter emits no tool parts
+by default, and only `output: { status }` with `toolParts: true`), there are no
+files, attachments, artifacts, or images,
+no goals/queue/steer UI, and reopening restores only a text snapshot. For
+anything else, use [the default conversation embed](#embed-the-conversation-default).
+
+One option object per conversation, one server handler for your endpoint.
+Tenants map to organization workspaces, conversations map to deterministic
+sessions, and the organization API key never leaves your server.
+
+```ts
+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!, // the organization id is derived from the key
+  source: "acme-app", // labels your product's tenants and users (default "app")
+});
+
+const chat = await og.chat({
+  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
+  create: { sandboxBackend: "none" }, // raw create-request passthrough for a pure chat
+});
+
+const reply = await chat.send("hello"); // creates the session on the first send
+console.log(reply.text); // or String(reply); the answer, without progress commentary
+
+// Per message: model policy and model-visible page context (not shown in the transcript).
+await chat.send("Why did revenue dip?", {
+  model: "gpt-5.5",
+  reasoningEffort: "low",
+  modelContext: "Viewing dashboard 42, range 2026-09-01..2026-09-28",
+});
+
+for await (const chunk of chat.stream("and then?")) {
+  if (chunk.type === "text") process.stdout.write(chunk.text);
+  if (chunk.type === "pending") await chat.respond({ requestId: chunk.pending.requestId, decision: "approve" });
+}
+
+// Your endpoint. `resolve` is your auth hook: identity comes from the request
+// you authenticated, never from the body. The handler reads the client's
+// conversation id itself (x-opengeni-conversation header, or the wire format's
+// own field) and authorizes as `user`; return `conversation` from resolve only
+// when the host names it, which is required when there is no `user`.
+export const handler = createChatHandler(og, {
+  resolve: async (request) => {
+    const session = await getSessionFromCookie(request);
+    if (!session) return new Response("Unauthorized", { status: 401 });
+    return { tenant: session.accountId, user: session.userId };
+  },
+  // format: "vercel" | "openai-chat" | "openai-responses" (default "native");
+  // a request may override it with the x-opengeni-chat-format header.
+});
+export const GET = handler; // conversation history, for restoring the chat on reload
+export const POST = handler; // send a message, or answer a pending request at .../respond
+```
+
+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.
+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.
+
+Pick the isolation per session with `agentAccess` (which other sessions the
+agent may reach) and `memory` (what it remembers), all inside one workspace that
+shares the customer's documents, instructions, and integrations:
+
+| Scenario                                          | `agentAccess` | `memory`      |
+| ------------------------------------------------- | ------------- | ------------- |
+| Agent confined to its chat tree (support desk)    | `"session"`   | `false`       |
+| One user's chats see each other, not other users' | `"user"`      | `"user"`      |
+| Everything in the tenant shared                   | `"workspace"` | `"workspace"` |
+| Shared agent access, no memory                    | any           | `false`       |
+
+To keep an existing `useChat` route with its own request body, stream the chat
+into your AI SDK response yourself. The Vercel format speaks the v1 UI message
+stream used by AI SDK 5, 6, and 7 (tool approval requests need 6 or later):
+
+```ts
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+import { uiMessageStreamParts } from "@opengeni/sdk/chat";
+
+export async function POST(request: Request) {
+  const { messages, dashboardId } = await request.json(); // your own body
+  const me = await authenticate(request);
+  const chat = await og.chat({ tenant: me.accountId, user: me.userId, conversation: me.chatId });
+  const text = lastUserText(messages);
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      const chunks = chat.stream(text, { modelContext: `Dashboard ${dashboardId}` });
+      for await (const part of uiMessageStreamParts(chunks, { framing: false })) {
+        writer.write(part as never);
+      }
+    },
+  });
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+Opengeni's own tool activity is omitted by default because those tools are not
+in your typed tool set; pass `toolParts: true` (or `createChatHandler(og, {
+toolParts: true })`) to emit them as `dynamic`, provider-executed tool parts.
+Pending approvals are always emitted as dynamic tool parts with a
+`tool-approval-request`.
+
+The chat handler is backend-only: connect a custom or compatible frontend to
+its protocol. For the full React agent experience, use `SessionConversation`
+with `OpenGeniClient` and authenticated session routes, not this simplified
+chat protocol. The normal SDK preserves files, tools, approvals with policies,
+forks, and realtime voice.
+
 ## Related-work discovery
 
 `listAgentTopology` returns a bounded hierarchy page plus provider-neutral
@@ -91,6 +695,35 @@ the advisory UI without changing stored evidence or API authority. See
 [`docs/work-discovery.md`](../../docs/work-discovery.md) for ranking, bounds,
 claim lifecycle, and rollout semantics.
 
+## Full-history message search
+
+`searchSessionMessages(workspaceId, { query, sessionId?, groupBy?, archiveStatus?, limit?,
+cursor? }, { signal? })` searches durable user and **completed assistant** text,
+including unloaded history. It returns every non-overlapping literal occurrence,
+not tools, reasoning, model context, or delta-only assistant output.
+
+Each match has a durable `eventId`/`sequence`, a UTF-16 `messageMatchOffset`, and
+`snippet: { text, matchStart, matchEnd }` with original-text UTF-16 offsets.
+Results include `nextCursor`, `hasMore`, cumulative `matchedMessageCount` and
+`matchedOccurrenceCount`, `scannedMessages`, and `countIsExact`. Keep following
+cursors even on empty pages while `hasMore` is true; counts are provisional until
+exhaustion. Cancel superseded searches with the third argument's AbortSignal.
+This is a live, authorized traversal rather than a frozen snapshot; restart to
+refresh after concurrent history or visibility changes.
+
+For workspace search, `groupBy: "session"` returns the first hit per matching
+session and skips that session's remaining history, keeping prolific messages
+from filling multiple picker pages. It cannot be combined with `sessionId`.
+In grouped mode both matched counters count session representatives, not full
+per-session message/occurrence totals; `scannedMessages` counts only visited
+messages. Cursors bind the grouping mode. Omit it for every-occurrence Find.
+
+The method and types are exported from the ordinary SDK and browser entry.
+Use `listEventPage` around the hit's sequence for bounded context, and use the
+returned search snippet when a large source message's ordinary projection does
+not include the hit. Never download complete history to perform Find locally.
+See [the API contract and bounds](../../docs/session-message-search.md).
+
 ## Session visibility and forks
 
 For organizations with session-tenancy activation, a canonical managed-cookie
@@ -126,49 +759,143 @@ user decision. A quiescence conflict identifies the stable blocker after live
 turns, goals, realtime, schedules, workspace writers, retained processes, and
 sandbox access have been settled. Forks copy exact same-workspace durable
 conversation content but no live turn, goal, credential, Connection/delegation,
-personal grant, Variable Set, Rig, MCP server configuration, process, sandbox
+personal grant, vault policy, task vault, Sandbox Environment, MCP server configuration, process, sandbox
 identity, pin, or workflow. Destination visibility and acknowledgement are
 idempotency-bound.
 
-## Personal-resource grants
+## Archived session history import (server only)
 
-The same canonical managed-cookie owner can manage explicit personal-resource
-delegations after organization activation. Pages are bounded to one exact kind;
-the server derives the only valid action and returns the full credential-free
-delegation to attach through the resource's ordinary session API.
+Use `@opengeni/sdk/session-history-import` to migrate historical conversations
+into read-only archives. These functions take `client` first, use its ordinary
+`requestJson` transport, and are not eager client methods or root helper exports:
+
+Create requires `sessions:create`; append requires `sessions:control` and the same
+authenticated importer. With `asUser`, the user's permissions apply rather than
+the organization key's permissions.
 
 ```ts
-const page = await browserClient.listUserResourceAuthorities(workspaceId, {
-  resourceKind: "connection",
-  limit: 50,
+import { OpenGeniClient } from "@opengeni/sdk";
+import {
+  importArchivedSession,
+  appendArchivedSessionEvents,
+} from "@opengeni/sdk/session-history-import";
+
+const og = new OpenGeniClient({
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
+  apiKey: process.env.OPENGENI_API_KEY!,
 });
-const authority = page.authorities[0];
-if (!authority) throw new Error("No personal Connection is available");
+// 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.
+  title: "Original conversation",
+  createdAt: "2025-04-01T09:30:00Z",
+  visibility: "user_private",
+});
+const appended = await appendArchivedSessionEvents(actor, workspaceId, imported.importId, {
+  batchId: "thread-42:batch-0001", // Stable; also persist this exact body first.
+  offset: imported.nextOffset,
+  events: [{
+    type: "agent.message.completed",
+    createdAt: "2025-04-01T09:31:00Z",
+    payload: { text: "Historical answer", channel: "final" },
+  }],
+});
+// Persist imported.session.id and appended.nextOffset in the migration ledger.
+```
 
-const issued = await browserClient.issueUserResourceGrant(workspaceId, authority.authorityId, {
-  scope: "user",
-  resourceKind: "connection",
-  mode: "session",
-  context: "workspace_shared",
-  sessionId,
-  expectedAuthorityEpoch: current.tenancy.authorityEpoch,
-  workspaceSharedAcknowledged: true,
+External mapping equivalents take `(client, source, externalId, ...)`:
+`importExternalWorkspaceArchivedSession` and
+`appendExternalWorkspaceArchivedSessionEvents`. These resolve an existing
+mapping; neither import form creates a workspace or grants membership. A bare
+organization key creates a shared, ownerless archive. Use `asUser` for the
+verified creator/owner; private imports require existing private-session
+enablement. Preserve source visibility rather than widening it on failure.
+
+The subpath exports `ImportArchivedSessionRequest/Response`,
+`AppendArchivedSessionEventsRequest/Response`, `ArchivedSessionImportEvent` and
+`SessionImportedArchive` types. Requests accept at most 100 events / 1 MiB
+serialized UTF-8 JSON and 256 KiB per event. IDs and titles are bounded to 200
+characters. Import events default to `[]`; append batches must be non-empty.
+Events carry `{ type, createdAt, turnId?, payload }`: a finite supported historical
+type, ISO timestamp, optional UUID/null correlation and JSON-object payload.
+Source timestamps support at most millisecond precision; normalize finer dates
+explicitly and retain originals in the ledger. Negative-zero JSON is rejected.
+
+Exact create replay returns `created: false`; exact append replay returns
+`replayed: true`. `offset` is a zero-based imported-event count, not a timeline
+sequence. Retain the exact actor, mapping, IDs, offset and bodies for uncertain
+retries; new batches use the acknowledged `nextOffset`. Changed key reuse or
+an out-of-order new offset returns 409. Helpers propagate `OpenGeniApiError`,
+including `outcomeUnknown`, and do not automatically retry mutations.
+
+Import is timeline-only: completed messages, calls/results and goals may be
+historical facts, but no model-facing history, live goal, pending decision or
+execution is restored. `session.importedArchive` has
+`{ importId, importedAt, readOnly: true }`, independent of personal archive state.
+Render through the unchanged `SessionConversation` and session proxy; never
+offer Send or Steer. Continuing an imported archive is unsupported in v1.
+The proxy does not expose import routes. Re-upload files through existing APIs
+and replace references before import; preserve additional source metadata and
+source/destination IDs in the host ledger. See
+[Migrating from embedded Opengeni](../../docs/product-integration.md#migrating-from-embedded-opengeni).
+
+## Connected accounts
+
+Authenticated messages use the initiating user's eligible connected accounts.
+Conversation visibility does not share account access. Queued work, retries and
+child work retain the initiating user. No per-conversation connection grant is
+required. Multiple eligible accounts require an explicit account choice:
+
+```ts
+const accounts = await browserClient.listOwnConnectionAccounts(workspaceId);
+// When choosing among multiple accounts, use the exact eligible server/account pair.
+const selection = { serverId: "mail", connectionId: accounts[0]!.id };
+```
+
+General personal-resource grants for documents and other resource
+kinds remain available through the root/core SDK. They do not authorize native
+connected accounts.
+
+## Workspace credentials, webhooks, and sandbox image
+
+Configure these with an organization key or workspace admin session. Secrets are
+returned once; store them when you create the resource. Protocol and payloads:
+[`docs/workspace-integrations.md`](../../docs/workspace-integrations.md).
+
+```ts
+const { secret: providerSecret } = await client.putWorkspaceCredentialProvider(workspaceId, {
+  url: "https://product.example/opengeni/credentials",
+});
+const { secret: webhookSecret } = await client.createWorkspaceWebhook(workspaceId, {
+  url: "https://product.example/opengeni/events",
+  eventTypes: ["turn.completed", "turn.failed"],
 });
 
-await browserClient.revokeUserResourceGrant(workspaceId, issued.grant.grantId);
+// In your HTTP handlers, verify the raw body before parsing it:
+const { event } = await verifyWebhookEvent({ body: rawBody, headers, secret: webhookSecret });
+const request = await verifyCredentialProviderRequest({
+  body: rawBody,
+  headers,
+  secret: providerSecret,
+});
 ```
 
-The SDK deliberately exposes only exact-session and standing (`always`) grant
-management. It does not expose standalone `once`, custom expiry, scheduled or
-cross-workspace authority, or an atomic create-session-and-attach workflow.
-Revocation prevents future reads but cannot retract output already shared.
+To check an endpoint now, `testWorkspaceWebhook(client, workspaceId, webhookId)` sends a
+signed `webhook.test` event (acknowledge it with any 2xx) and
+`testWorkspaceCredentialProvider(client, workspaceId)` sends a request with
+`purpose: "test"`; both come from `@opengeni/sdk/workspace-integrations` and return
+what the endpoint answered, naming returned credentials but never their values.
+
+`listWorkspaceSandboxImages` returns the deployment's allowlisted images; set one
+with `updateWorkspaceSettings(workspaceId, { defaultSandboxImage })`.
 
-## Scheduled connection authority
+## Personal schedules
 
-Agent schedules may carry explicit personal Connection authority. The public
-request contains only the credential-free server, Connection, and common-user
-grant tuple returned by the authority-selection API; the SDK never receives or
-stores provider credentials:
+A schedule created by an authenticated human or their active agent records that
+human as its immutable owner. Only that owner or their verified agent may edit,
+run, pause or delete it. Each occurrence resolves the owner's current accounts;
+accepted retries retain their original identity and account selection.
 
 ```ts
 const task = await client.createScheduledTask(workspaceId, {
@@ -176,18 +903,27 @@ const task = await client.createScheduledTask(workspaceId, {
   schedule: { type: "calendar", hour: 8, minute: 0, timeZone: "Europe/Oslo" },
   runMode: "reusable_session",
   agentConfig: { prompt: "Triage the new support issues" },
-  connectionAuthorities: [selection],
+  connectionAccounts: [selection],
 });
 ```
 
-PATCH semantics are deliberate: omit `connectionAuthorities` to preserve the
-exact prior immutable selection, pass `[]` to clear it, or pass a non-empty
-array to replace and revalidate it. Execution-changing edits that preserve
-personal authority must be made by the same causal human; use an explicit fresh
-selection when authority should move. `once` grants are consumed by the durable
-scheduled occurrence, not by an activity attempt, so retries reuse the same run
-receipt. `listScheduledTaskRuns` exposes terminal occurrence state while private
-Connection ids, subjects, and authority snapshots stay server-side.
+Account selections narrow eligible accounts; they never transfer ownership.
+Omitting `connectionAccounts` on update preserves the selection. Passing an
+empty array clears explicit account choices without changing the schedule owner.
+Service-owned schedules retain service execution and do not acquire a human's
+personal accounts. Run history remains credential-free.
+
+A schedule freezes its connectors, accounts and (when an agent created it)
+Opengeni tools. For the owner, `listScheduledTasks` and `getScheduledTask`
+include a read-only `policyDrift` naming what is out of date, and
+`listScheduledTaskRuns` includes `accessFailures` for runs that could not use a
+connector. `listScheduledTaskAccessAttention` lists schedules whose latest run
+failed that way, and schedules that cannot start because a chosen account can no
+longer be used (`unavailableAccounts`, with a null `runId`). A signed-in owner
+re-freezes with their current access through
+`refreshScheduledTaskAccess(workspaceId, taskId, { executionDigest, leaveOut })`,
+where the optional `leaveOut` keeps named default connectors or Opengeni tools
+off; API keys and agents cannot. See [`docs/scheduled-task-access.md`](../../docs/scheduled-task-access.md).
 
 Deleting a task is externally idempotent and immediately removes it from live
 lists and quota, but the server retains a tombstone plus run/session/turn audit
@@ -259,7 +995,7 @@ import {
   createBrowserEditableArtifactSession,
 } from "@opengeni/sdk/editable-artifacts";
 
-const client = new OpenGeniClient({ baseUrl: "https://api.example.com" });
+const client = new OpenGeniClient({ baseUrl: process.env.OPENGENI_API_BASE_URL! });
 const artifact = await client.getEditableArtifact(workspaceId, artifactId, {
   replicaId,
 });
@@ -270,7 +1006,7 @@ const kernels = {
 } as const;
 const { editableArtifactKernelRuntime } = await kernels[artifact.modality]();
 const session = createBrowserEditableArtifactSession({
-  baseUrl: "https://api.example.com",
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
   workspaceId,
   artifact,
   storageAuthority,
@@ -308,7 +1044,7 @@ shown below; it owns no state or authority of its own.
 
 `OpenGeniClient.interaction` is the framework-free resource facade over the same
 public BrowserSession, ComputerSession, identity, auth, network-route, and human
-intervention APIs used by OpenGeni itself. It adds no second state or execution
+intervention APIs used by Opengeni itself. It adds no second state or execution
 path: facade methods call the ordinary typed transport, and every mutation still
 uses the canonical generation fences, operation receipt, permission check, and
 placement controller.
@@ -323,6 +1059,8 @@ const browser = await client.interaction.browsers.currentOrOpen({
 const { targets } = await browser.tabs.list();
 const target = targets.find((candidate) => candidate.selected) ?? targets[0]!;
 const page = await browser.observe(target.id);
+const screenshot = await browser.screenshot(target.id, { fullPage: true });
+// screenshot.data is bounded image bytes; mediaType and dimensions travel with it.
 
 const receipt = await browser.act({
   operationId: crypto.randomUUID(),
@@ -339,6 +1077,17 @@ if (receipt.state === "outcome_unknown") {
 }
 ```
 
+`browser.targetState(targetId)` reads generation fences without an accessibility
+tree. `browser.readDom(targetId, request)` returns a bounded element or count
+query using those fences; sensitive values are redacted.
+
+The flat `client.openBrowserTargetWithInventory(workspaceId, browserSessionId,
+{ url })` explicitly opens a tab and returns the owned tab inventory and its
+generation fences without a page observation. The default
+`client.openBrowserTarget(...)` and `browser.tabs.open(...)` still return page
+observations. Older controllers can refuse the inventory method; do not retry an
+uncertain creation through another tab-open method.
+
 Browser identities are immutable version graphs: live browser state stays
 private until `browser.publishRevision(...)` explicitly creates a new revision.
 Protected auth fills resolve connection secrets only inside the broker/controller
@@ -358,10 +1107,13 @@ assign product types such as app, page, dashboard, or gallery. List pages are
 bounded and expose both `truncated` and an opaque `nextCursor` so callers never
 mistake a partial page for the complete workspace catalog.
 
-The initial web renderer supports semantic HTML, inline CSS, CSS-only
-interactions, and inline SVG. It removes JavaScript, event handlers, forms,
-embeds, external URLs, and other active or navigation-capable markup before
-rendering. Executable artifacts require a later, stronger isolation boundary.
+Each Site version retains one self-contained executable HTML runtime, its
+bounded editable source bundle, and the exact canonical tool identities it
+requested. The web host renders that runtime in an opaque-origin sandboxed
+iframe. Credentials, cookies, API URLs, workspace ids, and parent DOM authority
+never enter the iframe; `@opengeni/sdk/site` uses a single parent-owned
+`MessagePort` that exposes only the retained tool allowlist intersected with the
+current viewer's live workspace catalog.
 
 ```ts
 let cursor: string | undefined;
@@ -381,7 +1133,131 @@ return the exact source session, turn, attempt, and execution generation that
 published them. Version and event history are bounded; inspect
 `versionsTruncated` and `eventsTruncated` on the detail response.
 
-Omit `firstPartyMcpTools` for the complete OpenGeni tool catalog. An explicit
+## Workspace tools
+
+The browser-safe SDK exposes the same gateway catalog and executor used by
+model MCP calls and Codemode. Generated declarations augment the lazy namespace
+for exact installed-tool types; canonical `{ serverId, toolName }` identity and
+the server-side catalog remain authoritative.
+
+Known calls use `POST tools/invoke` directly, with no preceding workspace
+catalog request. The API selects one exact authorized account/connector; a
+selected MCP provider may still require its own `tools/list`. Symbolic paths
+use the canonical registry projection and reject ambiguity before connecting.
+Cold calls use the current definition. `$resolve({ identity })` returns one
+entry and a `definitionDigest`; pass it as `expectedDefinitionDigest` to require
+that complete public definition before execution. Digests never grant access.
+Returned executed metadata preserves structured-output unwrapping without a
+catalog load.
+
+`$catalog()` and `$declarations()` remain explicit full discovery. For an older
+API or Site host, set `toolGatewayMode: "catalog"` explicitly on the client;
+there is no automatic downgrade or retry after an unknown invocation outcome.
+The targeted SDK caches bounded per-target metadata, shares only resolution
+loads, and retries at most once after a typed pre-execution
+`tool_definition_stale`; explicit nonretryable or outcome-unknown flags veto
+replay even when a transport labels an error stale. Explicit pins are not
+silently dropped when malformed: only `undefined` means no explicit pin.
+The same retry veto applies to retained v1/catalog mode and Site host adapters.
+For saved Site bundles with code-only retry classifiers, the host's legacy call
+projection wraps executed stale-named provider errors as
+`site_tool_execution_failed`, retaining the complete original diagnostic at
+`result.structuredContent.error.providerError`. Success outputs and ordinary
+provider errors are unchanged; genuine known preexecution stale refresh remains
+available. Stale-named transport errors without that proof use
+`site_tool_call_failed` and retain the original code in their message.
+Pins are not silently advanced. An approved call uses the server's executable-effect and
+private-authority binding, not an implicit full-public-entry pin; supply
+`expectedDefinitionDigest` when that additional precondition is wanted.
+Changed executable effect or private authority requires reapproval. Operation IDs are correlation
+keys, not general idempotency for unapproved calls.
+
+```ts
+const tools = client.tools.forWorkspace(workspaceId);
+const documents = await tools.docs.search({ query: "launch plan" });
+```
+
+An approval-required call needs a server-issued capability. A trusted host
+shows its approval UI first, then asks for one token bound to the current human,
+workspace, operation id, exact tool identity, executable effect, Site context,
+private authority and arguments. Targeted approvals use a distinct version-2 binding, never a v1
+catalog digest.
+An Ask-to-Allow policy transition can settle matching pending provenance with
+or without the token, but never ignores a supplied invalid token or a consumed
+operation. Public definition pins remain optional and may reject policy/prose
+drift without consuming the pending approval.
+The token expires after five minutes, is stored only as a hash, and is consumed
+once by the matching call.
+
+Connection-backed tools configured for both provider policy and one-shot human
+approval are omitted from this HTTP catalog until their provider adapter can
+preflight credential and resource authorization before consuming the token.
+
+```ts
+const operationId = crypto.randomUUID();
+const identity = { serverId: "linear", toolName: "issues_update" };
+const input = { issueId, state: "Done" };
+const approval = await tools.$approveTarget(identity, input, { operationId });
+
+await tools.$call(identity, input, {
+  operationId,
+  approvalToken: approval.approvalToken,
+});
+```
+
+The retained `$approve()` method and explicit `toolGatewayMode: "catalog"` use
+the legacy protocol described below. Tokens returned by `$approve()` on the
+same facade retain that routing; externally retained legacy tokens must pass
+`approvalBinding: "catalog"`. Never reinterpret a legacy token as a targeted
+approval.
+
+When a legacy call or approval request receives the typed
+`409 details.code = "catalog_stale"` response, the SDK refreshes the catalog,
+re-resolves the exact identity or generated namespace path, preserves the
+operation id (generating it before the first attempt when omitted), and retries
+once. A call that already carries an approval token cannot reuse that
+single-use capability after the catalog digest changes; instead it throws
+`OpenGeniToolReapprovalRequiredError` with the refreshed identity and digest so
+the trusted host can show approval again for the same operation id.
+
+Concurrent callers share one in-flight catalog request (`$catalog` and every
+call path). Each caller's `signal` cancels only its own wait; the shared request
+is cancelled only when every waiter has aborted, and a failed load is not
+cached. Calls rejected as stale on the same digest share one refresh started
+after the first such rejection while it remains the current catalog, and an
+explicit `$catalog({ refresh: true })` always starts a new request.
+
+A call's `catalogDigest` is checked against the exact catalog entry it invokes:
+the API may accept an unchanged entry from a catalog digest whose unrelated
+entries have since changed, and then echoes that digest in the response. A
+changed, removed, or no-longer-authorized target entry still returns
+`catalog_stale` before execution.
+
+Reapproval is valid only before the original capability is consumed. Once a
+call crosses that boundary, the server retains a hash-only tombstone for the
+operation id and rejects another approval with
+`409 details.code = "tool_gateway_operation_already_started"` and
+`outcomeUnknown: true`. The host must reconcile the provider outcome; it must
+not turn an ambiguous call into a second approved execution by minting a fresh
+operation id automatically.
+
+Do not request approval capabilities speculatively or expose them to Site iframe
+code. The host projects only the active immutable version's requested identities,
+supplies the Site context on direct calls, and the server revalidates the active
+version and viewer's live authority. The requested set is a maximum allowlist,
+not an authority grant; ordinary gateway approval still applies. Archived Sites
+receive no tool bridge.
+
+An upgraded host advertises targeted calls to modern Site clients. Existing
+bundled Site clients retain their catalog/call protocol: the host obtains a
+bounded manifest for only that saved version's requested identities and
+translates calls using retained per-entry pins. They still make their initial
+catalog request; republishing with the modern client removes it. Unknown or
+evicted manifest digests fail before execution. Host-owned Site/version context
+and approval tokens are stripped from iframe requests. Local previews instead
+use their frozen attempt catalog and existing Codemode operation journal.
+
+Omit `firstPartyMcpTools` for the complete Opengeni tool catalog. An explicit
 `[]` exposes no broad first-party tools; attached resources and separately
 selected `files`/`docs` MCP servers are unaffected.
 
@@ -558,15 +1434,78 @@ await client.cancelSession(workspaceId, sessionId, {
   reason: "host record deleted",
   clientEventId: crypto.randomUUID(),
 });
+// approvalId is `approvals[].id` from the latest `session.requiresAction`
+// event (type SessionApprovalRequest: { id, name, arguments }); it is the
+// pending tool call id, not the event id.
 await client.sendApprovalDecision(workspaceId, sessionId, { approvalId, decision: "approve" });
 ```
 
+## Retry a failed session without changing its intent
+
+Try again is separate from Pause/Resume and `sendMessage`. Retain the request
+across an ambiguous transport response; never synthesize a continuation prompt:
+
+```ts
+const retryRequest = {
+  clientEventId: crypto.randomUUID(),
+  failureEventId, // the current durable turn.failed event id
+  model: selectedModel,
+  reasoningEffort: "high" as const,
+  latencyMode: "standard" as const,
+};
+const retry = await client.retrySession(workspaceId, sessionId, retryRequest);
+// { outcome: "accepted" | "replayed", turnId, failureEventId }
+```
+
+Requires `sessions:control` and session access. Recovery keeps the logical turn,
+original question, frozen authority, and completed history/tool results; it
+does not create a user message. Omitted policy fields retain the failed turn's
+selection. The selected policy is revalidated for new admission. A duplicate
+operation replays its receipt even after execution advances.
+
+HTTP 409 codes distinguish `RETRY_STALE_FAILURE`, `RETRY_EXECUTION_UNRESOLVED`,
+`RETRY_TOOL_OUTCOME_UNKNOWN`, `RETRY_PAUSED`, `RETRY_UNSUPPORTED_FAILURE`, and
+`IDEMPOTENCY_KEY_REUSED`. `RETRY_EXECUTION_UNRESOLVED` is transient: earlier
+execution is still settling. `RETRY_TOOL_OUTCOME_UNKNOWN` is permanent: a tool
+call in the turn has an unknown outcome and cannot be blindly replayed, so
+continue with a new message instead. A call proven never started does not block
+Retry. A deliberate Pause must
+be resumed separately. Failure without a retained logical turn, a settled
+scheduled occurrence, and idle credit exhaustion are not supported retry
+boundaries. See [run lifecycle](../../docs/run-lifecycle.md).
+
 ## Session tool policy and native web search
 
+For standalone credential maintenance, use the dedicated operation rather than
+sending a message:
+
+```ts
+const request = {
+  operationKey: crypto.randomUUID(),
+  updates: [{
+    id: "crm",
+    expectedCredentialVersion: 1,
+    expectedServerUrl: "https://tools.example.test/mcp",
+    headers: { Authorization: `Bearer ${replacementToken}` },
+  }],
+};
+const receipt = await client.rotateSessionMcpCredentials(workspaceId, sessionId, request);
+```
+
+Only exact existing inline servers without `connectionRef` are eligible. Both
+session control and MCP attach permissions, live session authorization, expected
+versions, and a quiescent credential-consumer boundary are required. This never
+sends a message, starts work, retries a failed turn, or refreshes an active
+client. Reconcile an ambiguous response with the same request/key; the SDK does
+not retry mutations automatically. Exact authorized replay returns the original
+receipt without a second write. Old receipt verification fails explicitly with
+503 if the deployment encryption key has been replaced. See the full
+[rotation contract](../../docs/session-mcp-servers.md#standalone-inline-credential-rotation).
+
 Omitting `tools` when creating a top-level session selects the current
 workspace-default capability policy, including the built-in `files` server.
 Passing `tools`, including `[]`, is an intentional fixed narrowing and can
-therefore disable file-download access for that session. OpenGeni's own web UI
+therefore disable file-download access for that session. Opengeni's own web UI
 keeps `files` enabled as a hidden default, while API and embedded clients retain
 exact control over the explicit list. Supported Responses providers attach
 their native bounded web-search tool independently of this MCP policy.
@@ -584,7 +1523,7 @@ const updated = await client.updateSessionToolPolicy(workspaceId, sessionId, {
 ```
 
 To keep a fixed allow-list, replace both connected MCP servers and individual
-OpenGeni tools atomically:
+Opengeni tools atomically:
 
 ```ts
 await client.updateSessionToolPolicy(workspaceId, sessionId, {
@@ -603,6 +1542,7 @@ it is not public web search.
 
 ```ts
 const goal = await client.getGoal(workspaceId, sessionId); // counters: autoContinuations, noProgressStreak
+const maybeGoal = await client.findGoal(workspaceId, sessionId); // null for a goal-less session (no 404)
 await client.pauseGoal(workspaceId, sessionId, { rationale: "manual review" });
 await client.resumeGoal(workspaceId, sessionId); // resets counters, re-arms continuations
 
@@ -624,7 +1564,7 @@ await client.rollbackGoalRevision(workspaceId, sessionId, appliedRevisionId, {
 call; the lower-level steps are exported for resumable/custom flows.
 
 Browser hosts need no storage credentials or per-application registration.
-OpenGeni authorizes the workspace request and returns a short-lived,
+Opengeni authorizes the workspace request and returns a short-lived,
 object-scoped signed URL; operators must configure the private object store to
 allow CORS from `*` so any product embedding the SDK can use that URL.
 
@@ -695,22 +1635,22 @@ Every public endpoint group has typed methods:
 
 | Group | Methods |
 | --- | --- |
-| Access + workspaces | `getAccessContext`, `listWorkspaces`, `createWorkspace`, `getWorkspace`, `updateWorkspace` |
+| Access + workspaces | `getAccessContext`, `listWorkspaces`, `createWorkspace`, `ensureWorkspace`, `getWorkspace`, `updateWorkspace` |
+| Managed organizations | `createOrganization` for first-time compatibility; `createAdditionalOrganization` for an already-onboarded human; `listOrganizationMemberships`, `listOrganizationInvitations`, `acceptOrganizationInvitation` |
 | Sessions + events | `createSession`, `listSessions`, `listSessionPage`, `listAgentTopology`, `getSession`, `getSessionLineage`, `updateSession`, `listEvents`, `sendEvent`, `sendMessage`, `steerMessage`, `pauseSession`, `resumeSession`, `cancelSession`, `sendApprovalDecision`, `streamEvents`, `openEventStream` |
 | Machines (bring-your-own-compute) | `listMachines`, `machineMetricsSeries`, `swapActiveSandbox`, `mintEnrollToken`, `lookupDeviceEnrollment`, `approveDeviceEnrollment`, `denyDeviceEnrollment` |
 | Turn queue | `getQueue`, `moveQueueItem`, `editQueueItem`, `steerQueueItem`, `deleteQueueItem` |
-| Goal | `getGoal`, `updateGoal`, `pauseGoal`, `resumeGoal`, `listGoalRevisions`, `listGoalRevisionPage`, `applyGoalRevision`, `rejectGoalRevision`, `rollbackGoalRevision` |
-| Scheduled tasks | `createScheduledTask`, `listScheduledTasks`, `getScheduledTask`, `updateScheduledTask`, `pauseScheduledTask`, `resumeScheduledTask`, `triggerScheduledTask`, `deleteScheduledTask`, `listScheduledTaskRuns` |
-| Variable sets | `listVariableSets`, `createVariableSet`, `getVariableSet`, `updateVariableSet`, `deleteVariableSet`, `setVariableSetVariable`, `deleteVariableSetVariable`; generic reads are metadata-only, while dedicated permissioned exact-value reads are part of the held client train |
+| Goal | `getGoal`, `findGoal`, `updateGoal`, `pauseGoal`, `resumeGoal`, `listGoalRevisions`, `listGoalRevisionPage`, `applyGoalRevision`, `rejectGoalRevision`, `rollbackGoalRevision` |
+| Scheduled tasks | `createScheduledTask`, `listScheduledTasks`, `getScheduledTask`, `updateScheduledTask`, `pauseScheduledTask`, `resumeScheduledTask`, `triggerScheduledTask`, `deleteScheduledTask`, `listScheduledTaskRuns`, `refreshScheduledTaskAccess`, `listScheduledTaskAccessAttention` |
+| Vaults | `client.vaults(workspaceId)` returns `listVaults`, `getVault`, `createVault`, `updateVault`, `deleteVault`, `syncVault`, `listItems`, `getItem`, `createItem`, `updateItem`, `deleteItem`, `restoreItem`, `moveItem`, `revealField`, `listFieldVersions`, `restoreFieldVersion`, `getSessionSecrets`, `setSessionVaultPolicy`, `installOnePassword`, `listOnePasswordConnections`, `replaceOnePasswordToken`, `disconnectOnePassword`, `listProviderVaults`, `linkProviderVault` and `createManagedProviderVault`. Reads are metadata-only; `revealField` is the one audited plaintext read. Agents use `{{secret:Vault/Item/field}}` references instead of values. Variable Sets were removed in 2.0.0 |
 | Files | `uploadFile`, `beginFileUpload`, `completeFileUpload`, `getFile`, `createFileDownloadUrl` |
 | Documents | `createDocumentBase`, `listDocumentBases`, `getDocumentBase`, `addDocument`, `listDocuments`, `reindexDocument`, `searchDocuments`, `searchKnowledge` (effective organization + workspace + immutable initiating-user personal scope) |
-| Packs | `listPacks`, `registerPack`, `getPack`, `enablePack`, `deletePack`, `listPackInstallations` |
 | Capabilities | `listCapabilities`, `createCapability`, `enableCapability`, `disableCapability`, `discoverMcpCapabilities` |
 | Plugin packages | `previewPlugin`, `installPlugin`, `previewPluginUninstall`, `uninstallPlugin` |
 | API Integrations | `listIntegrationDefinitions`, `listApiIntegrations`, `previewApiIntegration`, `startApiIntegrationOAuth`, `installApiIntegration`, `previewApiIntegrationUninstall`, `uninstallApiIntegration`, `listIntegrationFacets`, `configureIntegrationFacet`, `pauseIntegrationFacet`, `resumeIntegrationFacet`, `removeIntegrationFacet`, `browseGoogleDriveFacetSource`, `saveGoogleDriveFacetSource` |
 | Remote Skills | `previewSkillImport`, `installSkill`, `previewSkillUninstall`, `uninstallSkill` |
 | GitHub | `getGitHubApp`, `githubConnectUrl`, `listGitHubRepositories`, `syncGitHubRepositories`, `createGitHubAppManifest` |
-| API keys | `listApiKeys`, `createApiKey`, `deleteApiKey` |
+| API keys | Workspace: `listApiKeys`, `createApiKey`, `deleteApiKey`; organization: `listOrganizationApiKeys`, `createOrganizationApiKey`, `deleteOrganizationApiKey` |
 | Billing | `getBilling`, `getBillingUsage`, `getBillingEntitlements`, `createBillingCheckout`, `createBillingPortalSession` |
 
 `listIntegrationDefinitions` returns safe Integration Definition metadata without any
@@ -744,15 +1684,21 @@ reconsider — they can change with their counterpart, not with the SDK.
 
 ## Compatibility
 
-Clients and servers are compatible within the same **major** release-train
-version; evolution is additive within a major and both sides are tolerant
-readers. Official server builds expose `serverVersion` on `/healthz` and
-`/v1/config/client`. Full policy: `docs/architecture.md` §3.10.
+Clients and servers are compatible within the same **major** version of this
+SDK; evolution is additive within a major and both sides are tolerant readers.
+Official server builds expose `serverVersion` on `/healthz` and
+`/v1/config/client`. A route scheduled for removal answers with `Deprecation`
+and `Sunset` headers at least 90 days (and a major) ahead; the client reports
+each deprecated route once through the `onDeprecation` option (default: one
+`console.warn` per route; `false` silences it). Full policy:
+`docs/design/api-compatibility-policy.md`.
 
 ## Proxy through your own API
 
-Keep your OpenGeni API key on your server and re-emit the stream to your own
-browser clients. The re-emitted wire format is identical to OpenGeni's SSE
+For the React conversation, use the packaged
+[`createSessionProxyHandler`](#embed-the-conversation-default). For a custom
+backend route, keep your organization API key on your server and re-emit the
+stream to your own browser clients. The re-emitted wire format is identical to Opengeni's SSE
 stream, so the browser side can consume it with this same SDK (or a plain
 `EventSource`), including resume via `?after=` / `Last-Event-ID`:
 
@@ -760,7 +1706,10 @@ stream, so the browser side can consume it with this same SDK (or a plain
 // Your server (Hono, Next.js route handler, Bun.serve, workers, ...):
 import { OpenGeniClient, proxySessionEventStream } from "@opengeni/sdk";
 
-const client = new OpenGeniClient({ baseUrl, apiKey });
+const client = new OpenGeniClient({
+  baseUrl: process.env.OPENGENI_API_BASE_URL!,
+  apiKey: process.env.OPENGENI_API_KEY!,
+});
 
 export function GET(request: Request): Response {
   // authenticate *your* user, resolve their session id, then:
@@ -789,3 +1738,20 @@ Hosts, test doubles, and same-origin proxies must import
 configuration or contract header. Do not copy its string value: the revision is
 an executable compatibility boundary, and `getClientConfig()` intentionally
 fails closed when server and SDK revisions differ.
+
+### Action review facts
+
+`getToolActionReview(workspaceId, sessionId, approvalId)` returns version 1 facts
+for an exact prepared connector action: title, selected account/count, material
+effects, optional provider-sourced examples, bounded fields, reason, status and
+available actions. Use `sendApprovalDecision` for the existing authenticated
+human decision. Facts never grant execution authority.
+
+`getToolReviewDetails(workspaceId, sessionId, approvalId, { actionDigest, path,
+offset })` pages through the saved selection/values (25 rows per page). The
+reference is tied to the original action digest and requires the same session
+visibility permission; it never re-runs a search. Secret/write-only fields stay
+hidden. A missing legacy snapshot may return 404; other authorization or transport
+failures must not be interpreted as permission to execute. Responses are private
+and non-cacheable. Review states distinguish waiting, execution, cancellation,
+failure and uncertain outcome. Exact stored arguments are never client-editable.