@opengeni/sdk 4.0.2 → 4.0.5-canary.39115048408002

package/README.md

@@ -1,6 +1,6 @@
 # @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.
@@ -10,88 +10,334 @@ workspaces, Personal-workspace exclusion, tenant mapping, and external Skill
 ownership—start with the canonical
 [product integration guide](../../docs/product-integration.md).
 
-Zero runtime dependencies. Needs only WHATWG `fetch` and streams, so it runs in
-Node 18+, Bun, Deno, browsers, and edge runtimes.
+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.
 
-## Chat quick start (`@opengeni/sdk/chat`)
-
-The fastest way to put OpenGeni behind an existing chat: 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.
+## 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:
 
 ```ts
-import { OpenGeni, createChatHandler } from "@opengeni/sdk/chat";
+// lib/opengeni.ts (server only: the organization API key never reaches the browser)
+import { Opengeni } from "@opengeni/sdk/chat";
 
-const og = new OpenGeni({
-  apiKey: process.env.OPENGENI_API_KEY!,
-  organizationId: process.env.OPENGENI_ORGANIZATION_ID!,
-  // baseUrl defaults to https://app.opengeni.ai; source (default "app") labels your product.
-});
+export const og = new Opengeni({ apiKey: process.env.OPENGENI_API_KEY! });
+```
 
-const chat = await og.chat({
-  tenant: "acme", // one workspace per customer, created on first use
-  user: "u_42", // opaque end-user label (required for memory: "user")
-  conversation: "c_9", // stable id, namespaced to user; the session id is derived from both
-  agentAccess: "session", // "session" (default) | "user" | "workspace"
-  memory: "user", // "session" | "user" | "workspace" | false; default follows agentAccess
-  create: { sandboxBackend: "none" }, // raw create-request passthrough for a pure chat
+```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
 });
+```
 
-const reply = await chat.send("hello"); // creates the session on the first send
-console.log(reply.text); // or String(reply)
+```tsx
+// app/assistant/assistant.tsx (browser): no provider, client, or workspace id.
+"use client";
+import { OpenGeniChat } from "@opengeni/react";
+import "@opengeni/react/compiled.css";
 
-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" });
+export function Assistant() {
+  return <OpenGeniChat baseUrl="/api/opengeni" />; // chat list + conversation
 }
+```
 
-// 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 scopes it to `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 };
+`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
   },
-  // 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
+
+// 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)
 ```
 
-Conversation ids are namespaced per user: the same `conversation` for two
-`user` labels reaches two sessions, so a client cannot continue another user's
-chat by guessing its id. 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.
+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.
 
-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:
+`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:
 
-| Scenario                                          | `agentAccess` | `memory`      |
-| ------------------------------------------------- | ------------- | ------------- |
-| Every chat isolated (support desk)                | `"session"`   | `"session"`   |
-| 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`       |
+```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)}` } },
+    ],
+  }),
+});
+```
 
-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.
+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
 
@@ -99,7 +345,7 @@ forks, and realtime voice.
 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!,
 });
 
@@ -120,14 +366,14 @@ 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
+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_ORGANIZATION_API_KEY!,
+  apiKey: process.env.OPENGENI_API_KEY!,
 });
 
 const organizationId = process.env.OPENGENI_ORGANIZATION_ID!;
@@ -146,17 +392,40 @@ if (workspace.kind !== "shared") {
 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
-complete organization-workspace inventory.
+organization-workspace inventory allowed by the key's live scope.
 
 Organization key administration uses `listOrganizationApiKeys`,
-`createOrganizationApiKey`, and `deleteOrganizationApiKey`. The key token from a
+`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, and every key reports its tier as `apiKey.access`. Either tier can call
-`listOrganizationSessions(organizationId, { limit, cursor, endUser, status })`
-for one page of sessions across every shared workspace (each row carries its
+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.
 
@@ -166,10 +435,10 @@ 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 Pack Skills normally remain workspace-managed. A Pack may instead
-mark guidance as `session_selected`; installation then exposes it to no agent
+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,
+`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
@@ -193,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
@@ -237,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
@@ -272,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)
+
+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:
 
-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.
+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!,
+});
+// 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 authority = page.authorities[0];
-if (!authority) throw new Error("No personal Connection is available");
+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, {
@@ -322,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
@@ -405,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,
 });
@@ -416,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,
@@ -454,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.
@@ -469,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(),
@@ -485,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
@@ -512,6 +1115,27 @@ 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.
 
+Site AI can return directly into an app without any conversation UI:
+
+```ts
+import { createOpenGeniSiteClient } from "@opengeni/sdk/site";
+const site = createOpenGeniSiteClient();
+const result = await site.ai.run({ initialMessage: appPrompt, idempotencyKey: actionId });
+if (result.status === "completed") renderResult(result.text);
+```
+
+The app defines the prompt, context and output presentation. This helper uses
+native sessions and events with the same permissions, approvals, model access
+and billing; it is not a second executor. New Site work is private per viewer
+and excluded from ordinary workspace discovery. `pending` and `cancelled` are
+not successful results; model failure rejects. Retain the `onSession` handle
+to observe again using `site.ai.result(id, { turnId })`, without creating work.
+An `after` cursor returns only subsequent output; omit it for full replay.
+Aborting observation does not cancel native execution. See
+[`site-conversations.md`](../../docs/site-conversations.md) and
+[`site-session-embed`](../../examples/site-session-embed) for optional chat and
+headless inline examples. Do not store private handles in shared Site Data.
+
 ```ts
 let cursor: string | undefined;
 do {
@@ -537,6 +1161,38 @@ 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" });
@@ -544,7 +1200,13 @@ 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, catalog digest, exact tool identity, and arguments.
+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.
 
@@ -556,7 +1218,7 @@ preflight credential and resource authorization before consuming the token.
 const operationId = crypto.randomUUID();
 const identity = { serverId: "linear", toolName: "issues_update" };
 const input = { issueId, state: "Done" };
-const approval = await tools.$approve(identity, input, { operationId });
+const approval = await tools.$approveTarget(identity, input, { operationId });
 
 await tools.$call(identity, input, {
   operationId,
@@ -564,7 +1226,13 @@ await tools.$call(identity, input, {
 });
 ```
 
-When a call or approval request receives the typed
+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
@@ -573,6 +1241,19 @@ 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
@@ -588,7 +1269,16 @@ 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.
 
-Omit `firstPartyMcpTools` for the complete OpenGeni tool catalog. An explicit
+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.
 
@@ -765,15 +1455,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.
@@ -791,7 +1544,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, {
@@ -810,6 +1563,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
 
@@ -831,7 +1585,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.
 
@@ -907,12 +1661,11 @@ Every public endpoint group has typed methods:
 | 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` |
@@ -952,15 +1705,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 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
+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`:
 
@@ -968,7 +1727,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:
@@ -997,3 +1759,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.