@beeuni/sdk 0.1.0

package/README.md

@@ -0,0 +1,1234 @@
+# @beeuni/sdk
+
+The **single, opinionated data layer** for the Beeuni API. One typed
+client wraps both the **Beeuni REST API** and the **agent runtime** so a
+host app — web, mobile, reference — imports **only `@beeuni/sdk`**. The SDK
+owns its types: the transcript is Beeuni's own format (`beeuni.transcript.v1`),
+and the package depends on no harness SDK. (The no-raw-`backendApi`/`authenticatedFetch` rule
+below is the target state, not yet fully true of apps/web — see Rules of the
+road.)
+
+> Philosophy: **one Beeuni token, one client, every action a method.** Keys never
+> leave the server; mutations own their side-effects there; the host states intent.
+
+📖 **Full documentation:** [beeuni.ai/docs/sdk](https://beeuni.ai/docs/sdk) —
+getting started, the full client, sessions, React hooks, and the subpath modules.
+The REST API has an auto-generated reference at
+[api.beeuni.ai/v1/docs](https://api.beeuni.ai/v1/docs).
+
+---
+
+## Install
+
+```bash
+npm install @beeuni/sdk
+```
+
+```ts
+import { createBeeuni } from "@beeuni/sdk";
+
+const beeuni = createBeeuni({
+  backendUrl: "https://api.beeuni.ai/v1",
+  getToken,
+});
+await beeuni.projects.list();
+```
+
+### Call external systems through Connectors
+
+Use one data plane for every Connector provider. A user token binds
+the project explicitly. An agent-minted session token already carries its
+project scope, so it can use the top-level fallback.
+
+```ts
+const connectors = projectId
+  ? beeuni.project(projectId).connectors
+  : beeuni.connectors;
+
+await connectors.catalog();
+await connectors.tools();
+await connectors.search('send email');
+await connectors.describe('gmail.send_email');
+await connectors.call('gmail.send_email', { to, subject, body });
+await connectors.accounts('gmail');
+const { ref } = await connectors.uploadAttachment(bytes, {
+  filename: 'invoice.pdf',
+  contentType: 'application/pdf',
+  connector: 'microsoft-graph', // the connector the file is for
+});
+// `ref` is { $beeuni_attachment: '<id>' }. The gateway swaps in the file:
+// as an attachments[] element it becomes the provider's attachment item,
+// in a string field it becomes the base64. The bytes never enter call args.
+await connectors.call('microsoft-graph.sendmail', {
+  user: 'sender@example.com',
+  body: { message: { subject: 'Invoice', attachments: [ref] } },
+});
+```
+
+A Connector defines callable tools. A Connection stores one authorization for
+that Connector. Credentials remain server-side and never enter the sandbox.
+
+#### Typed calls
+
+`beeuni connectors types --out beeuni-connectors.d.ts` writes a declaration
+file that fills `ConnectorActionRegistry`. `callAction` then types `args` and
+`output` from it. The request and the result are the same as `call`:
+
+```ts
+const r = await connectors.callAction('linear', 'list_issues', { team: 'CORE' });
+r.output?.issues; // typed from the action's output schema
+```
+
+One connector as a handle: `run` returns the output itself and throws
+`ConnectorCallError` (`code`, `connectUrl`, `availableAccounts`,
+`upstreamStatus`, `retryAfterSeconds`) or `ConnectorApprovalPendingError`;
+`paginate` follows a cursor and throws `ConnectorPageLimitError` (with
+`nextArgs`) past `maxPages`; `useConnectorQuery` (`@beeuni/sdk/react`) caches a
+read. Guide: `/docs/sdk/connectors`; runnable: `examples/13-connectors-as-code.ts`.
+
+```ts
+const linear = beeuni.project(projectId).connector('linear');
+const { issues } = await linear.run('list_issues', { team: 'CORE' });
+await linear.describe(); // actions with input and output schemas
+await linear.accounts();
+```
+
+An action outside the file accepts any object and returns `output: unknown`.
+Managed Composio and Pipedream connectors publish no output schema, so their
+`output` stays `unknown`. `ConnectorArgs<'linear', 'list_issues'>` and
+`ConnectorResult<'linear', 'list_issues'>` name the same types.
+
+#### Choose which account a call runs as
+
+One Connector can hold the project's shared account and each member's own. List
+the accounts a caller may use, then name one on the call:
+
+```ts
+const accounts = await connectors.accounts('gmail');
+// [{ connection_id, label, owner_type: 'project' | 'member', is_default }]
+
+const result = await connectors.call('gmail.send_email', { to, subject, body }, {
+  account: 'Support inbox',   // a label, a connection id, `me`, or `project`
+});
+result.account; // { connection_id, label, owner_type } — the identity that ran
+```
+
+`account` takes a connection label (case-insensitive), a connection id, or one
+of two selector words: `me` (the caller's own default private account) and
+`project` (the default account shared with the whole project). Omit it and
+resolution takes the caller's own default first, then the project's.
+
+A named account is never silently substituted. If it does not match one this
+caller is entitled to, the call is denied with `connector_not_connected` and the
+denial lists the accounts that were available. Every successful call echoes
+`account`, so a transcript can always show which identity acted.
+
+Nothing connected yet? Start a hosted authorization and say who the new account
+belongs to:
+
+```ts
+await project.connectors.pipedream.connect('gmail', { owner: 'me' });      // my own
+await project.connectors.pipedream.connect('gmail', { owner: 'project' }); // shared
+
+// Or hand a human a link instead of authorizing inline:
+await project.setupLinks.requestConnector({ slug: 'gmail', owner: 'project' });
+```
+
+`owner` defaults to `me`. Creating a `project`-owned account requires
+`project.connector.write`.
+
+#### Call from an App, a Convex action, or a script
+
+The call is the same everywhere. The credential decides which accounts it
+reaches:
+
+| Where the code runs | `createBeeuni` options | Acts as | Reaches |
+|---|---|---|---|
+| App, browser | `backendUrl: '/_beeuni/api/v1'`, `getToken: beeuniAppViewerToken()` | the viewer | shared accounts the viewer may use, and the viewer's own private accounts |
+| App, server | `createAppViewerBeeuni(request, { backendUrl })` | the viewer | the same |
+| Convex action, App job with no viewer | `getToken: async () => process.env.BEEUNI_API_KEY!` (a `beeuni_sa_…` service account bearer a person minted) | the service account | shared accounts nobody narrowed; never a private account |
+| External program, CI | `getToken: async () => process.env.BEEUNI_API_KEY!` (a `beeuni_pat_…`) | you | your shared and private accounts |
+
+The browser path needs the App's viewer scope set to `api`
+(`beeuni apps access <app> --viewer api`); with `identity` a call answers
+`403 insufficient_scope`. A service account answers `403` until a person
+grants it a project role (`beeuni access grant --service-account <id> --role
+member --project <id>`). Never put a provider API key in an App or a Convex
+deployment when a connector exists. Guide: `/docs/sdk/connectors`.
+
+### Upload prompt attachments before Send
+
+Create one controller per composer. `add(file)` starts a private project upload
+without waiting for a session runtime. Subscribe to `getSnapshot()` for tile state.
+
+```ts
+const attachments = beeuni.project(projectId).attachments.createController();
+const localId = attachments.add(file);
+const unsubscribe = attachments.subscribe(() => render(attachments.getSnapshot()));
+
+// Inside the submit handler. Send never waits for uploads.
+const ids = attachments.getSnapshot().attachments.map((item) => item.id);
+attachments.submit(ids); // hand-off: the composer clears, the uploads continue
+paintMessage(text, ids);
+try {
+  const parts = await attachments.whenReady(ids); // handle-only parts, in `ids` order
+  await beeuni.session(projectId, sessionId).prompts.create({
+    clientMessageId,
+    messageId,
+    parts: [{ type: 'text', text }, ...parts],
+  });
+  attachments.forget(ids); // release; does not delete storage objects
+} catch (error) {
+  attachments.reclaim(ids); // back to the composer, with the failed file's state
+}
+```
+
+React consumers use `usePromptAttachments(projectId)` from `@beeuni/sdk/react`.
+It returns the controller methods plus the reactive `attachments` list. It omits
+`dispose`, `subscribe`, and `getSnapshot`, and keeps its identity until the list
+changes.
+
+Files move through `pending`, `uploading`, `processing`, `ready`, `error`, or
+`aborted`. Progress counts bytes sent. Progress snapshots are throttled: one per
+whole-percent change, at most ten per second per upload. The default concurrency
+is two files.
+Limits are 50 MiB per file, 100 MiB per message, and 20 files. Empty files are
+rejected. Refuse Send only while a selected file is `error` or `aborted`.
+
+`whenReady(ids, { signal })` resolves once every upload is `ready`. It rejects
+when one fails, is aborted or removed, or `signal` aborts. A rejected wait does
+not stop the upload.
+
+Ownership: `submit(ids)` hands entries to one send. They leave `attachments` and
+stop counting toward the limits. `dispose()` aborts and deletes only listed
+work, so a composer that unmounts after Send (a navigation, a remount) does not
+cancel its held uploads. The controller object lives as long as the send's `whenReady`
+promise references it. Call `forget(ids)` after the prompt POST succeeds, or
+`reclaim(ids)` when a failed send restores its draft. `forget()` with no argument
+releases only the listed selection. A host that keeps a failed send on screen
+keeps its entries: `retry(id)` reaches a handed-off entry after `dispose()`.
+
+`retry(localId)` resumes the same upload and preserves the original File. After
+`attachment_size_mismatch` or `attachment_failed` the server keeps no usable
+handle, so `retry` uploads the File again as a new attachment. An expired upload
+cannot retry: `retry` throws, and the item error carries code
+`attachment_expired`. `remove(localId)` removes the entry, aborts its upload, and
+resolves at once. It deletes unbound storage best-effort and never rejects; a
+failed or refused DELETE leaves the object to the 24-hour expiry.
+`abort(localId)` cancels unfinished work. `dispose()` aborts listed work and
+deletes its uploads best-effort: no send holds them, and drafts keep no handle.
+Call it on non-React cleanup; the hook handles unmount and project changes.
+Unused uploads expire after 24 hours.
+
+Selections live in memory only. Never persist a File, blob URL, signed URL, or
+upload handle in a draft.
+
+For non-composer uploads, call `beeuni.project(projectId).attachments.upload(file,
+{ signal, onProgress, onUpload, resume })`. The server selects the transport in the
+handle's `upload` field:
+
+- `kind: 'direct'` (default): one `PUT` of the whole file to `upload.url` with
+  `upload.headers` and no Authorization header. Hosts with `XMLHttpRequest`
+  (browsers, React Native) report sent bytes; other hosts use `fetch` and report
+  0, then the full size. An expired URL, or one Storage refuses with 400/401/403,
+  is re-signed once for the same `attachment_id`; the server creates no second
+  upload. A `409` from Storage means an earlier attempt already stored the file.
+- `kind: 'chunked'`: sequential authenticated `PUT`s of `upload.chunk_size` bytes.
+  The SDK accepts any positive `chunk_size`. Only a deployment whose edge drops
+  large request bodies selects it.
+
+Completion then verifies the stored bytes. Retain the `onUpload` handle for manual
+same-ID recovery. If completion answers `409 attachment_not_uploaded`, `onUpload`
+reports the direct handle with `received_bytes: 0`, so a resume sends the file
+again. Initiation, the upload, and completion retry timeouts, network errors,
+429, and 5xx with jittered exponential backoff. The budget is 60 seconds from the
+first failure, so a long upload that fails late still retries. Completion also
+retries `attachment_processing`, with a five-minute budget. Initiation never
+retries 402 (a `BillingError`: the account cannot run) or 429
+`attachment_budget_exceeded` (40 unfinished uploads or 500 MiB of unsent uploads
+for the user; unused uploads expire within 24 hours). The server answers or
+refuses one completion within 105 seconds; each completion request allows 120
+seconds. Caller aborts never retry.
+
+A sent attachment's reference is released 1 hour after its prompt is delivered,
+and when its session or project is deleted. The next maintenance sweep then
+removes the file, and its `attachment_id` can no longer be sent.
+Completed `attachment_id` parts use platform prompt routes. Runtime `sendParts`
+continues to accept runtime URL parts. Legacy platform URL parts remain supported.
+
+## No bundler, no framework
+
+The published package ships a browser IIFE bundle alongside its ESM `dist/` —
+no build step required:
+
+```html
+<script src="https://unpkg.com/@beeuni/sdk"></script>
+<script>
+  const beeuni = Beeuni.createBeeuni({ backendUrl, getToken });
+</script>
+```
+
+> **CORS:** a `<script>` page calls the API from its own origin, so that origin
+> must be in the API's CORS allowlist. Beeuni's own domains and `localhost:3000/3010`
+> are allowed out of the box; any third-party origin (or a local page on another
+> port) needs adding via the API's `CORS_ALLOWED_ORIGINS` — otherwise the browser
+> blocks the request before it leaves the page. A Beeuni-hosted App needs no
+> allowlist entry: it sets `backendUrl: '/_beeuni/api/v1'`, its own origin
+> (see "A Beeuni-hosted App is already signed in").
+
+## Entry points
+
+`@beeuni/sdk` is the canonical entry — everything framework-free lives there.
+Four others exist, each for a reason that fits in one sentence:
+
+| Entry                         | Why it is separate                                         |
+| ----------------------------- | ---------------------------------------------------------- |
+| `@beeuni/sdk/react`           | React is a peer dependency                                 |
+| `@beeuni/sdk/server`          | imports `node:async_hooks`                                 |
+| `@beeuni/sdk/wire-message-id` | the wire-id clock alone, one file with no imports (also at root) |
+| `@beeuni/sdk/internal/*`      | unsupported, outside semver                                |
+
+Install the optional peers before you use the React entry:
+
+```bash
+npm install @beeuni/sdk react @tanstack/react-query
+```
+
+Older subpaths (`@beeuni/sdk/projects-client`, `/turns`, …) still work and are
+`@deprecated`. Import from the root instead — see **Entry points** below for
+the four that are real, and **API-MAP.md**'s Stability table for the full
+list of aliases (20 of them).
+
+> **React Native / Expo:** REST works. Live streaming works with a host
+> transport: pass `configureBeeuni({ eventStreamTransport })` (one connection's
+> messages over the wire your runtime has, e.g. `react-native-sse`), and report
+> foreground and network changes with `notifyHostSignal`. `apps/mobile` runs
+> `useSession` from `@beeuni/sdk/react` this way.
+
+## Quick start
+
+```ts
+import { createBeeuni } from "@beeuni/sdk";
+
+const beeuni = createBeeuni({
+  backendUrl: "https://api.beeuni.ai/v1",
+  getToken: () =>
+    supabase.auth
+      .getSession()
+      .then((s) => s.data.session?.access_token ?? null),
+});
+
+// Projects
+const projects = await beeuni.projects.list();
+const detail = await beeuni.project(pid).detail();
+await beeuni.project(pid).secrets.upsert({
+  name: "LOCAL_TOOL_TOKEN",
+  value,
+  strategy: "runtime",
+  consumer: "sandbox",
+});
+// Who can use a value: [] = everyone (default), or people and groups. A
+// narrowed value reaches only them — directly, or in their own private
+// sessions; never a shared session or a trigger.
+await beeuni.project(pid).secrets.upsert({
+  name: "DEEL_API_TOKEN",
+  value: deelToken,
+  strategy: "broker",
+  consumer: "connector",
+  shared_with: [{ principal_type: "user", principal_id: userId }],
+});
+await beeuni.project(pid).secrets.upsert({
+  identifier: "anthropic-primary",
+  name: "ANTHROPIC_API_KEY",
+  value: providerKey,
+  strategy: "broker",
+  consumer: "llm_gateway",
+});
+// When pooled_provider_secrets and llm_gateway are enabled for the project,
+// a new account secret is available to this project's members by default.
+const shared = await beeuni.accounts.secretResources.create(accountId, {
+  project_id: pid,
+  label: "Anthropic backup",
+  provider_id: "anthropic",
+  name: "ANTHROPIC_API_KEY",
+  value: providerKey,
+  consumer: "llm_gateway",
+  strategy: "broker",
+});
+// Restrict it to selected members when needed. The creator keeps access.
+await beeuni.accounts.secretResources.setAccess(accountId, shared.secret_id, "members", [memberUserId]);
+await beeuni.session(pid, sid).providerSecretPool.set("anthropic", [shared.secret_id]);
+const { pools, can_edit } = await beeuni.session(pid, sid).providerSecretPool.list();
+// Passing null to set() resets the session to the project default.
+const visibleSessions = await beeuni.project(pid).sessions.list();
+const projectInventory = await beeuni
+  .project(pid)
+  .sessions.list({ scope: "project" }); // manager only; inaccessible rows omitted
+// Top-level sessions the caller started; spawned sessions load under their parent.
+const mine = await beeuni.project(pid).sessions.list({ parent: "root", startedBy: "me" });
+const found = await beeuni.project(pid).sessions.list({ parent: "root", q: "nightly" }); // searches every visible session
+const spawned = await beeuni.project(pid).sessions.list({ parent: mine[0].session_id });
+// React: useProjectSessions(pid, { parent: "root", startedBy: "me" }), useSessionChildren(pid, parentId)
+const warm = await beeuni.project(pid).sessions.ensureWarm(); // ordinary session, pre-created
+
+// Sessions (id-bound handle)
+const s = beeuni.session(pid, sid);
+const cost = await s.cost(); // reads finalized LLM + compute cost; no runtime start
+await s.send("Build me a widget"); // provisions/resumes if needed, then prompts
+await s.rewind(userMessageId); // stages a reversible rollback on this session
+await s.restoreRewind(); // restores the removed path before the next prompt
+await s.previews();
+await s.participants(); // who can open the session
+await s.reloadConfig({ refresh_repo: false });
+await s.reloadConfigStream(
+  { refresh_repo: false },
+  (event) => event.type === "phase" && console.log(event.phase),
+);
+
+// The session verbs, bound to THIS session's own runtime (each provisions it first).
+const { messages, hasMore } = await s.messages({ limit: 50 }); // { info, parts }[], oldest first
+const { statuses, permissions, questions } = await s.pending();
+await s.answerPermission(permissions[0].id, "once"); // "once" | "always" | "reject"
+await s.answerQuestion(questions[0].id, [["Yes"]]); // null dismisses it
+await s.compact(); // only when health() lists `session.compact`
+```
+
+React consumers use `useAccountSecretResources(accountId)` and
+`useSessionProviderSecretPools(projectId, sessionId)` from `@beeuni/sdk/react`.
+The latter exposes `setPool.mutate({ providerId, secretIds })`. `null` restores
+inheritance; `[]` disables that provider for the session. Empty configured pools
+remain listed after their last resource is deleted. Successful writes refresh
+both the pool list and the session's provider-specific query cache.
+
+### Apps
+
+`beeuni.project(projectId).apps` deploys immutable App releases behind one stable URL, on the Fly.io model: releases, machines per process group, persistent volumes. New Apps use `private` access. Apps is an experimental project feature, so API operations return `404` until a project manager enables it.
+
+```ts
+const apps = beeuni.project(projectId).apps;
+const app = await apps.create({ slug: 'docs', name: 'Docs' });
+const artifact = await apps.artifacts.uploadArchive(tarGzBytes);
+await apps.deployments.create(app.app_id, {
+  artifact_id: artifact.artifact_id,
+  source: { kind: 'static', spa: true },
+});
+await apps.access.update(app.app_id, {
+  mode: 'restricted',
+  member_ids: [memberId],
+  group_ids: [groupId],
+});
+const browserSession = await apps.access.session(app.app_id);
+```
+
+Access modes are `private`, `project`, `restricted`, `public`, and `password`. An access session exchanges a five-minute URL for an eight-hour, host-only cookie. A stopped or idle App resumes on the same public request. Transient machine requests receive `202 app_starting` and `Retry-After: 3`.
+
+Branch on `app.capabilities` (`machines`, `scale`, `exec`, `volumes`, `snapshots`, `static`, …). A call for a capability the App lacks answers `409 app_capability_unsupported`. A backend (database, Convex) is an ordinary server App with a volume; there is no backend type.
+
+`apps.list()` returns only the Apps the caller may open under each App's access policy (a project manager sees all), so `viewer_can_access` is `true` on every listed App. A `get` of an App the caller cannot open answers `404`. Apps have no budget: account credits pay for App compute. An always-on App bills its machines 24/7; an on-demand App only while awake.
+
+```ts
+await apps.deployments.create(api.app_id, {
+  artifact_id, source: { kind: 'oci_image', image, command: ['node', 'server.js'] },
+  config: {                                              // the release config (beeuni.yaml apps.<name> ≈ fly.toml)
+    processes: { app: '', worker: 'node worker.js' },
+    http_service: { internal_port: 3000, access: 'app', processes: ['app'] },
+    mounts: [{ source: 'data', destination: '/data', initial_size_gb: 10, processes: ['app'] }],
+  },
+});
+const machines = await apps.machines.list(api.app_id);  // machine_id stays across releases
+await apps.scale(api.app_id, { worker: 3 });            // 0-20 per group, applied in the background
+const { exit_code, stdout } = await apps.exec(api.app_id, { command: ['ls', '/data'] });  // project.app.admin
+const [data] = await apps.volumes.list(api.app_id);
+const snap = await apps.volumes.snapshot(api.app_id, data.volume_id);
+await apps.volumes.restore(api.app_id, data.volume_id, snap.snapshot_id);  // project.app.admin
+await apps.update(site.app_id, { uses: ['api'], labels: ['frontend'] });    // the site may mint api tokens and bind to it
+```
+
+`@beeuni/sdk/react` adds `useAppMachines`, `useAppVolumes`, and `useAppVolumeSnapshots`.
+
+`send()` reads the persisted session model and
+agent before the first prompt on a handle. This prevents a snapshot-inherited
+runtime session from reusing stale snapshot defaults. A per-call choice
+overrides a `setModel()` or `setAgent()` choice. A handle choice overrides the
+persisted session default.
+
+### Saved session attachments
+
+`session.attachments.upload(file)` stores up to 50 MiB in private object storage. It
+returns `{ attachment_id, filename, mime, size, url }`. Use `url` in a file part sent to
+the prompt inbox. The API copies those bytes into the sandbox after startup. Uploads and `session.attachments.read(attachment_id)` do not start a
+sandbox. Reads return a `Blob` and require access to the session. Retries of the same `File`
+reuse the successful upload; an explicit `attachmentId` supports caller-managed retries.
+
+### Session labels and metadata
+
+Every session carries `labels: string[]` and a free-form `metadata` object. Set both
+at `project.sessions.create({ labels, metadata })`. `session.update({ labels })`
+replaces the labels; `session.update({ metadata })` merges keys, and a `null` value
+removes a key. `project.sessions.listPage({ labels })` returns only sessions that carry
+every given label, and `useProjectSessions(projectId, { labels })` does the same in
+React. Each label is 1–64 characters, at most 20 per session; one metadata write is at
+most 16,384 characters of JSON. Example: `examples/12-session-labels.ts`.
+
+### Who wrote each message
+
+`beeuni.session(projectId, sessionId).messageAuthors()` (or `getSessionMessageAuthors`) returns
+`{ authors, initial_author }`: `authors` maps a runtime message id to a `SessionMessageAuthor`,
+`{ kind: 'member', user_id, name, email, avatar_url }` or `{ kind: 'session', session_id, name, agent? }`.
+In React, `useSessionMessageAuthors(projectId, sessionId, messageCount)` reads the same data.
+
+### Which model answered a turn
+
+`beeuni.session(projectId, sessionId).modelUsage()` (or `getSessionModelUsage`) returns
+`{ latest, billed_cost, turns }` from the gateway's request record. `latest` is
+`{ served_model, fallback_from, at }` for the newest answered request: `served_model` is the model
+that answered, and `fallback_from` is the routed model when a fallback model answered in its place.
+`turns` maps the runtime message id of each prompt to `{ served_models, fallback_from, billed_cost }`.
+A transcript message carries only the model its turn asked for. In React,
+`useSessionModelUsage(projectId, sessionId)` reads the same record.
+
+### React runtime
+
+`useSession(projectId, sessionId)` opens the session runtime returned by
+`POST /start`. The runtime is OpenCode or pi; the hook reads the same routes,
+transcript and events from both. The hook owns messages, rewind and restore,
+cancellation, commands, permissions, and questions. Hosts do not construct
+runtime routes. A feature one harness lacks is a capability: gate its control
+with `runtimeSupports(health?.capabilities, 'session.rewind')`. pi lists
+`session.subagents` only, so rewind, compaction, slash commands, the todo list
+and the runtime config document stay hidden or empty on a pi session.
+
+Every session saves its transcript at the end of each turn. `useSession` reads saved
+messages from the platform database while `/start` continues. It uses the
+server-validated runtime session id and lets the live read reconcile the saved messages by ID.
+A live read that returns no messages keeps the saved messages on screen: it means the computer
+lost its state, not that the conversation is empty. The first live read with messages reconciles them.
+Missing or rejected history falls back to the existing runtime path.
+
+`useSession().savedTranscript` says whether that saved conversation can show before the
+computer wakes: `loading` while a saved copy may still arrive, `shown` once messages are in
+`messages`, and `none` when nothing can show until the runtime answers. A host renders
+placeholder rows on `loading` and its boot screen only on `none`.
+`useSession().conversationEmpty` is true when the saved copy proves the conversation empty
+(a complete read of the runtime found no messages), no turn ended since, and nothing is open
+or queued. A host renders the composer then, not a boot screen.
+
+A host that registers a saved-copy store (`setSavedCopyStore(createSavedCopyStore({ storage,
+userId }))`) gets the kept copy painted before the first frame; the server's copy reconciles
+into it by message ID. `createPersistedQueryCache` does the same for accounts, projects and
+the paged session list. Both are per user and bounded; clear both on sign-out. Session
+states have one set of words for every host: `sessionListStatus`, `SESSION_LIST_STATUS`,
+`sessionConnectionLabel`, `SESSION_NOTICE`, and `turnRetryLabel`.
+
+A server-rendered host can seed a known runtime session pin while `/start` runs:
+
+```tsx
+useSession(projectId, sessionId, {
+  initialRuntimeSessionId: persistedSession.runtime_session_id ?? persistedSession.opencode_session_id,
+});
+```
+
+Use only a pin that the host authorized for the same `(projectId, sessionId)`.
+The seed hydrates cached content. It does not choose the runtime identity.
+The pin returned by `/start` always replaces a stale seed. The SDK also scopes
+runtime query and synchronization controllers to the sandbox runtime. Two
+sandboxes cannot share browser cache state when a snapshot exposes the same
+runtime session id during adoption. `opencode_session_id` is the older name
+of `runtime_session_id`; read it only as the fallback above.
+
+After a project replaces its repository, a session created before the
+replacement still starts. It runs the project's CURRENT config release and
+converges like any other session. What stays true of it is physical: its
+`/workspace` clone came from the old repository while `origin` now resolves to
+the new one. The two histories are unrelated, so a push from that clone needs a
+rebase first.
+
+`repositoryMode: 'previous'` is accepted and changes nothing:
+
+```tsx
+useSession(projectId, sessionId, { repositoryMode: 'previous' });
+```
+
+The server reads it as telemetry. Keep it only for callers built against the
+older behaviour.
+
+Message retries keep the originating sandbox URL after navigation. A `404` or
+`410` message read stops automatic retries and preserves the cached transcript.
+An explicit reconciliation can recover the controller when the session returns.
+
+## The facade surface
+
+`createBeeuni(config)` returns one client. The table below is illustrative, not
+exhaustive — see `API-MAP.md` for the full per-domain surface:
+
+| namespace | what |
+|---|---|
+| `beeuni.projects` | list · get · detail · create · provision · update · archive · llmCatalog · modelPicker · sandboxTemplates · sessions (+ more: `listForAccount`, `sandboxHealth`, `createSession`) |
+| `beeuni.accounts` | list · get · create · members · invites · `secretResources.{list,create,rotate,delete,grant,revoke,setAccess}` · `tokens.{list,create,revoke}` (account-scoped CLI PATs, `beeuni_pat_…`) · `audit.{log,export,webhooks.*}` (filterable project/session reconstruction log) · `branding.{get,update,uploadAsset,removeAsset,reset}` (Enterprise organization branding: logo / icon / favicon, light + dark, product name) (+ more: `updateName`, `leave`, `invite`, `removeMember`, `updateMemberRole`) |
+| `beeuni.billing` | entitlement/usage reads: `accountState` · `accountStateMinimal` · `transactions` · `transactionsSummary` · `creditBreakdown` · `usageHistory` · `usageRollup` · `sessionCosts.{list,get}` · `tierConfigurations` — plus a curated mutation surface: `subscription.{createPortalSession,cancel,reactivate,cancelScheduledChange,prorationPreview}` · `credits.{purchase,autoTopupSettings,configureAutoTopup}`. `checkout.{createSession,confirmSession}` and `subscription.scheduleDowngrade` are deprecated: they reject with `ENDPOINT_RETIRED` |
+| `beeuni.marketplace` | public marketplace catalog browse + sources (not project-scoped): `items` · `item` · `itemFile` · `marketplaces` · `featured` · `sources.{list,add,remove}` — distinct from the install-scoped `project(id).marketplace` |
+| `beeuni.github` | account-scoped GitHub App installs and repo linking: `getInstallation` · `listInstallations` · `listLinkableInstallations` (each entry carries `linked_to_other_accounts`, a count and never a tenant name) · `listRepositories` · `listRepositoryBranches` · `linkInstallation` · `saveInstallation` · `deleteInstallation` · `linkRepository` (`source: 'managed'` imports a repository the instance backend holds — instance operator only, and mutually exclusive with `installation_id`) · `replaceProjectRepository` (changes an existing project's repository with an expected old URL; accepts a repository-scoped PAT or a temporary GitHub user proof for a repository-scoped App grant; can atomically copy selected shared runtime secrets from another project in the same account) |
+| `beeuni.gitBackend` | the instance git backend ("Beeuni managed", one per deployment, never an account connection): `get()` → `{configured, kind: 'app'|'pat'|null, owner}` (any authenticated user) · `repositories({search?, limit?})` (instance operator only; 403 otherwise) |
+| `beeuni.notifications` | the caller's notifications, across accounts: `list({ limit?, before? })` (inbox page + `unread_count`) · `markRead({ ids } \| { all: true } \| { sessionId })` · `preferences` · `updatePreferences({ kinds })` (push and email per kind) · `webPushPublicKey` · `registerWebPushSubscription` · `unregisterWebPushSubscription` · `registerDeviceToken` · `unregisterDeviceToken` (native Expo push). Muting one session is `session(pid, sid).setWatch(false)`. Hooks: `useNotificationInbox`, `useNotificationPreferences`, `useSessionWatch`. Inbox rows, Web Push, email, and session watch are served only for projects with the `notification_center` flag on, off by default; with it off, the session creator's phone still gets the push |
+| `beeuni.validateToken()` | pasted-API-key validation helper — `GET /accounts/me`, never throws, resolves `{valid, identity?, error?}` |
+| `beeuni.connectors` | Connector data plane for an agent-minted session token: `catalog` · `tools` · `search` · `describe` · `call` (`{ account }`) · `accounts` · `uploadAttachment` |
+| `beeuni.project(id)` | id-bound handle: `.apps` (stable App URLs, access, artifacts, deployments, logs, rollback, start/stop, machines (`machines.list/start/stop/restart/destroy`, `scale`, `exec`), volumes (`volumes.list/create/update/destroy/snapshots/snapshot/restore/fork`), and `token`) · `.secrets` · `.access` · `.connectors` (data plane + configuration + Connections) · `.policies` · `.triggers` (cron / webhook / monitor / event; `.eventTypes({ connector })` lists a connector's app events) · `.files` · `.git` · `.changeRequests` (incl. `requestChanges`) · `.sessions` · `.tokens` (project-scoped CLI PATs — the `BEEUNI_TOKEN` shape) · `.marketplace` / `.registry` (install/update/remove catalog items) · `.setupLinks.{requestSecret,requestConnector}` (agent-minted secret-entry / connector links) · `.validateManifest` · `.gitToken` · `.setDefaultAgent(name)` · `.session(sid)` (+ more namespaces: `.review`, `.approvals`, `.gateway` (incl. `.routing` and `.playground`), `.channels`, `.modelDefaults`, `.sandbox`) |
+| `beeuni.session(pid, sid)` | id-bound handle: lifecycle (`get`/`update`/`delete`/`start`/`restart`/`stop`/`reloadConfig`/`reloadConfigStream`/`setSharing`/`participants`/`watch`/`setWatch`/`presence`/`previews`/`commit`/`publicShares`/`ensureReady`) · `providerSecretPool.{list,get,set}` · finalized `cost()` · `send`/`abort`/`rewind`/`restoreRewind`/`setModel`/`setAgent` · `transcript()` · `.files` · runtime URL helpers (`health`/`previewUrl`/`proxyUrl`) · runtime REST escape hatches: `stream()` and the deprecated `.runtime` |
+| `beeuni.runtime()` | the runtime REST client for the active sandbox (the SDK's own `RuntimeClient`, frozen at the `@opencode-ai/sdk` 1.18.23 route shapes); use a session-scoped handle in multi-tenant code |
+
+Runnable, self-contained scripts for the highest-value flows live in
+[`examples/`](./examples): list projects with a PAT, send + stream, the
+multi-tenant server-wrapper pattern, headless transcript rendering, cost
+pass-through / re-billing, and session files + project secrets. Each file's
+header comment states the env vars and the exact `bun run examples/….ts`
+invocation.
+
+Wrapper backends can attach bounded, non-secret scalar context when creating a
+session. It is persisted across cold recovery/replacement restart and exposed
+to the agent only as one `BEEUNI_SESSION_CONTEXT` JSON envelope:
+
+```ts
+await beeuni.project(projectId).sessions.create({
+  runtime_context: { workspace_id: "org_123", locale: "de" },
+});
+```
+
+Do not put credentials in this map. For a white-label/backend wrapper, create an
+operator-managed connection, store its credential through the dedicated
+credential endpoint, and pass only the non-secret connection id at session create:
+
+```ts
+const project = beeuni.project(projectId);
+const connection = await project.connectors.connections.reconcile({
+  connector_alias: "customer-data",
+  owner_type: "external",
+  owner_id: wrapperUserId,
+  label: "Customer data",
+  metadata: { tenant_ref: wrapperTenantReference },
+});
+
+// Omit `auth` when creating to apply source-advertised authentication.
+const auth = await project.connectors.auth.discover({
+  slug: "hubspot",
+  provider: "postman",
+  spec: "https://github.com/HubSpot/HubSpot-public-api-spec-collection",
+});
+await project.connectors.connections.updateCredential(connection.connection_id, {
+  value: shortLivedCapability,
+  kind: "secret",
+});
+await project.sessions.create({
+  runtime_context: { locale: "de" },
+  connector_bindings: {
+    "customer-data": { connection_id: connection.connection_id },
+  },
+});
+```
+
+For bring-your-own authorization, each logged-in member creates their own
+connection without supplying an owner id; Beeuni derives ownership from the bearer
+token:
+
+```ts
+const connection = await project.connectors.connections.reconcileMember({
+  connector_alias: "gmail",
+  label: "My Gmail",
+});
+await project.connectors.connections.pipedreamConnect(connection.connection_id);
+// Complete OAuth, then:
+await project.connectors.connections.pipedreamFinalize(connection.connection_id);
+await project.sessions.create({
+  connector_bindings: { gmail: { connection_id: connection.connection_id } },
+});
+```
+
+Member connections are owner-only even for project managers, and sessions using
+one must remain private. A service account — an agent or a trigger — never
+reaches a member connection, only the shared project one. Project defaults
+remain shared; external/agent/subject connections remain operator-managed. Every connection is project/connector scoped
+and resolved on every Connector request, so revocation takes effect without a
+restart. Credentials are encrypted server-side and are never returned, placed
+in `BEEUNI_SESSION_CONTEXT`, or injected into the sandbox environment. Raw env
+and MCP configuration are not session-create inputs.
+
+`session.stream()` is a thin facade over the
+framework-free `openEventStream`
+primitive (also exported directly, for hosts that want to manage the client
+themselves): it resolves THIS handle's own runtime (`ensureReady()`), connects
+to that runtime's SSE endpoint, and hands you a `close()`-able handle. No React
+required — safe to call from a server-side "Beeuni as a Backend" wrapper
+(Node/Bun), a worker, or a CLI:
+
+```ts
+const handle = await beeuni.session(pid, sid).stream({
+  onEvent: (event) => console.log(event.type, event),
+  onGapRehydrate: (gapMs) => console.warn(`reconnected after a ${gapMs}ms gap`),
+});
+// later, to stop:
+handle.close();
+```
+
+`session.stream()` emits the runtime's events (`message.updated`,
+`message.part.updated`, `session.status`, `permission.*`, `question.*`, …),
+the same from OpenCode and pi. Use `useSession()` in React.
+
+Events arrive in batches, 16 ms apart. Consecutive `message.part.delta` events
+for one part field in a batch arrive as one event: `properties.delta` is their
+text joined in order, `id` is the last event's id, and `coalesced` lists the
+events it replaced.
+
+`@beeuni/sdk/react`'s `useRuntimeEventStream` uses the exact same primitive
+under the hood — it just also writes into the React Query cache.
+
+## Beeuni as a Backend (server-side)
+
+`createBeeuni()` stores its config — crucially, the bearer-token getter — in a
+process-wide singleton. That's correct for a host with one config for its whole
+lifetime (a browser tab, a CLI, a single-tenant server), but **unsafe for a
+server process handling concurrent requests for different end users**: two
+in-flight requests racing through `createBeeuni()`/`configureBeeuni()` with
+different tokens clobber each other, and the last write wins for every other
+in-flight request.
+
+`@beeuni/sdk/server` (Node/Bun only — never import it from a browser bundle;
+it statically imports `node:async_hooks`) fixes this with `AsyncLocalStorage`:
+
+```ts
+import { createScopedBeeuni } from "@beeuni/sdk/server";
+
+// Express/Hono/Bun.serve — any per-request handler. One scoped client PER
+// REQUEST; each end user's token stays isolated to that request's own async
+// call tree, even across `await`s, even under concurrency.
+app.get("/projects", async (req, res) => {
+  const beeuni = createScopedBeeuni({
+    backendUrl: process.env.BEEUNI_API_URL!,
+    getToken: async () => resolveBeeuniTokenFor(req), // per-end-user PAT/token
+  });
+  res.json(await beeuni.projects.list());
+});
+```
+
+`createScopedBeeuni(config)` has the same shape as `createBeeuni(config)` —
+every method call (including calls through `.project(id)` / `.session(pid, sid)`
+handles minted at call time) automatically runs inside that config's scope, and
+it never writes the process-global singleton. For middleware-style wrapping of
+an entire request body instead, use the lower-level primitive:
+
+```ts
+import { runWithBeeuni } from "@beeuni/sdk/server";
+
+app.use(async (req, res, next) => {
+  await runWithBeeuni(
+    { backendUrl, getToken: async () => resolveBeeuniTokenFor(req) },
+    async () => {
+      await next(); // every Beeuni call anywhere in this request sees THIS config
+    },
+  );
+});
+```
+
+A runnable version of the pattern is `examples/03-server-wrapper.ts`, and the
+full production-shaped reference (per-user project isolation, route policy,
+rate limiting, cost markup for re-billing) is `apps/whitelabel-demo` in wrapper
+mode — see its README.
+
+## Rendering chat (the headless chat kit)
+
+Everything needed to render an agent transcript without adopting any Beeuni
+UI: `classifyPart`/`classifyTurn` (framework-free, from the root entry)
+normalize all twelve part types of the Beeuni transcript format
+(`beeuni.transcript.v1`; both harnesses emit it) (text, reasoning, tool, file,
+subtask, patch, snapshot, agent, retry, compaction, step, + a forward-compat
+`unknown`) into a typed `ClassifiedPart`, and normalize a failed assistant
+turn's `info.error` into a `{ name, message }` `TurnError` — so "assistant
+message with zero parts but an error" renders as a failure, not silence.
+`renderParts` (`@beeuni/sdk/react`, though it has no React import) requires a
+renderer for **every** part kind at compile time, so a new part type is a
+build error at your call site instead of a silent drop in production:
+
+```tsx
+import { renderParts, type PartRenderers } from "@beeuni/sdk/react";
+import { classifyTurn } from "@beeuni/sdk";
+
+const renderers: PartRenderers<React.ReactNode> = {
+  text: (p) => <Markdown>{p.text}</Markdown>,
+  reasoning: (p) => <Thinking text={p.text} />,
+  tool: (p) => <ToolCard name={p.tool.name} status={p.tool.status} />,
+  file: (p) => <Attachment name={p.filename ?? p.url} />,
+  subtask: (p) => <Delegated agent={p.agent} />,
+  patch: (p) => <DiffStat files={p.fileCount} />,
+  retry: (p) => <Note>{`retrying (attempt ${p.attempt})`}</Note>,
+  compaction: () => <Note>context compacted</Note>,
+  snapshot: () => null, // internal checkpoint hash — nothing to show
+  agent: () => null, // inline @mention, already in the sibling text
+  step: () => null, // model-step bookkeeping
+  unknown: () => null, // forward-compat: newer server than client
+};
+
+function Turn({ message }: { message: MessageWithParts }) {
+  const { parts, error, isEmpty } = classifyTurn(message);
+  if (isEmpty && !error) return null;
+  return (
+    <>
+      {renderParts(parts, renderers)}
+      {error && <TurnFailed {...error} />}
+    </>
+  );
+}
+```
+
+The living reference is
+`apps/whitelabel-demo/src/components/chat/message-view.tsx` — one deliberate
+rendering decision per part kind, with the rationale for each `null`. For a
+memoized message-list binding use `useChatTurns(messages)` (`@beeuni/sdk/react`);
+for a no-React plain-text version of the same classification see
+`examples/04-render-transcript.ts`. On the live side, `narrowChatEvent`
+(root barrel) narrows the raw ~50-variant SSE union from `session.stream()` /
+`openEventStream` down to the curated `BeeuniChatEvent` union (~14 members) a
+chat UI actually dispatches on.
+
+## Composer agent and model lists (no React)
+
+The session composer's pickers are built from pure functions on the root
+entry, so every host — the web app through its hooks, React Native through
+the root import — offers the same agents and models and sends the same pick.
+`@beeuni/sdk/react`'s `useRuntimeAgents`, `useRuntimeProviders`,
+`useRuntimeLocal`, and `useModelStore` call these.
+
+| Function | Input → output |
+|---|---|
+| `projectConfigAgentsToRuntimeAgents(config)` | `/projects/:id/detail` config → agent roster, project default first |
+| `composerSelectableAgents(agents, { enableProjects?, includeSubagents? })` | roster → picker list (no hidden agents, no subagents, `project-manager` only with `enableProjects`) |
+| `resolveComposerAgent({ agents, boundAgent, defaultAgent, selectedAgent })` | → the agent to send, and `disabled` when none is accessible |
+| `pickerProviderList({ gatewayEnabled, modelPicker, runtimeProviders, llmCatalogProviders, secretNames })` | raw sources → provider list |
+| `flattenModels(providers, { providerMode })` | provider list → `ModelOption[]` (a `FlatModel` plus `id`, the ref a pick stores) |
+| `modelRefToKey(ref, gatewayEnabled)` | a stored ref (session pin, channel binding, trigger, agent `model`) → `ModelKey`; `beeuni/x` and `x` are one gateway model |
+| `createModelVisibility({ catalogModels, pins?, connectedProviderIds?, freeTier? })` | → default-visibility predicate |
+| `modelInDefaultView(model, { search, isStoreVisible, selected })` | → whether the empty-search picker shows the model |
+| `resolveModelDefault(modelDefaults, agentName)` | `/model-defaults` → agent → project → account → platform default |
+| `resolveComposerModel({ models, picks, serverDefault, globalDefault, agentModel, configModel, recent, providers })` | → `{ model, explicit, fallback }` |
+
+The root barrel reads catalog helpers from `@beeuni/llm-catalog/lite`, which
+never includes the ~7.6 MB models.dev snapshot, so a bundler that does not
+tree-shake (Metro) stays small.
+
+## Errors
+
+One typed hierarchy, produced by **every** HTTP layer — `backendApi`, the
+`authenticatedFetch`, the files client, the runtime REST client, and
+`ensureReady()` all throw/return the same classes (from
+the root barrel; `@beeuni/sdk/react` re-exports them too). They're real classes: `instanceof` works across every host, and
+`name`/shape are preserved for legacy `error.name === 'ApiError'` sniffers.
+
+- `ApiError` — any failed request; branch on `.status` / `.code` (e.g.
+  `'TIMEOUT'`, `'RUNTIME_UNAVAILABLE'`, `'ABORTED'`). Timeout errors carry
+  `.url` / `.endpoint` / `.timeout`.
+- `HeadlessAuthError extends ApiError` — `getToken()` returned null; the request was
+  never sent (`code: 'NO_SESSION'`).
+- `BillingError extends ApiError` — HTTP 402, with the backend's payload on
+  `.detail` and its machine code on `.code`.
+- `RequestTooLargeError extends ApiError` — HTTP 431 (usually a too-large
+  upload batch), with a `.detail.suggestion`.
+- `SessionNotReadyError` (root barrel) — a session handle's runtime-scoped
+  member (`.runtime`, `.previewUrl()`, `.proxyUrl()`) was touched before
+  `ensureReady()` resolved this session's own sandbox.
+
+The canonical server-side wrapper shape — catch a 402 and pass the payload
+through to your own client for re-billing, instead of leaking a Beeuni error:
+
+```ts
+import { ApiError, HeadlessAuthError, BillingError } from "@beeuni/sdk";
+
+try {
+  await beeuni.session(pid, sid).send(prompt);
+} catch (err) {
+  if (err instanceof BillingError) {
+    // 402 — surface the upgrade/cost payload under YOUR billing story.
+    return res.status(402).json({ reason: "quota", detail: err.detail });
+  }
+  if (err instanceof HeadlessAuthError)
+    return res.status(401).json({ error: "not authenticated" });
+  if (err instanceof ApiError)
+    return res.status(err.status ?? 502).json({ error: err.message });
+  throw err;
+}
+```
+
+Every non-streaming request also carries a **30s default timeout** (the
+long-lived SSE event stream is exempt), so a hung sandbox/daemon call can't
+wedge a server-side handler forever — it surfaces as an `ApiError` with
+`code: 'TIMEOUT'` instead.
+
+Idempotent reads (`GET`/`HEAD`) also absorb transient gateway blips: `502`,
+`503`, and `504` retry up to two times with 250ms → 500ms backoff before an
+`ApiError` is surfaced. Mutations and HTTP `500` responses are never retried.
+
+LLM session retries can carry the gateway's structured failure chain. Use
+`getRetryInfo(status)`. Its optional `details` field contains the final
+`provider`, gateway `code`, `requestId`, and ordered `attemptFailures`. Each
+failure identifies the provider, route model, resolved model, stage, upstream
+status when available, concrete code, and bounded message. Plain legacy retry
+messages remain supported and return `details: undefined`. When the runtime keeps
+only the HTTP error message, `getRetryMessage(status)` still returns the full
+gateway composite. That message includes the request ID and each candidate's
+provider, resolved model, HTTP status, code, and bounded message.
+
+## Entry points
+
+**There are four, plus one internal.** Everything framework-free lives at the
+root. `react` and `server` exist because each carries a dependency the root
+cannot; `wire-message-id` exists so a server can load one module, not the barrel.
+That is the whole map — learn it once.
+
+| import | when you use it | why it is separate |
+| --- | --- | --- |
+| `@beeuni/sdk` | **almost always.** `createBeeuni`, `configureBeeuni`, the REST surface, `files`, session URLs + health (`runtimeSupports` reads a runtime's `capabilities`), `classifyPart`/`classifyTurn`/`toolViewModel`/`toToolView`/`toolKind`, `openEventStream`, `narrowChatEvent`, the message queue, the error classes, and every domain type | — |
+| `@beeuni/sdk/react` | hooks and providers: `useSession`, every `useRuntime*` (each pre-W4 `useOpenCode*` name is a deprecated alias), `useChatTurns`/`renderParts`, the domain hooks | `react` is an **optional peer dependency**. Putting these at the root would force React on a CLI, a worker, or a React Native host |
+| `@beeuni/sdk/server` | `runWithBeeuni`, `createScopedBeeuni`, `getScopedConfig` — per-request config isolation in a Node/Bun backend | imports `node:async_hooks`. Never let it into a browser bundle |
+| `@beeuni/sdk/wire-message-id` | `mintWireMessageId`, `mintWireMessageIdAbove`, `newestWireIdClock`, `wireIdClock`, `wireIdClockDelta`, `maxWireIdClock`, `isWireIdAheadOf` — the OpenCode wire message-id clock | not a dependency split: the root exports the same names. A server that mints ids loads this one import-free module instead of the whole barrel |
+| `@beeuni/sdk/internal/*` | nothing, in host code | apps/web's zustand stores. Browser-only, **outside semver**, and not on the `window.Beeuni` global. Implementation detail that is regrettably visible |
+
+The root really is canonical, and that is a test rather than a promise:
+`src/root-canonical.test.ts` asserts that every name exported by every other
+isomorphic subpath is also exported from `@beeuni/sdk`. The only names it
+permits to be missing are the browser-only stores above — `zustand` is a
+forbidden import in the root's `isomorphic-core` tier, so they cannot live
+there.
+
+```ts
+import { createBeeuni, classifyTurn, listFiles, openEventStream } from '@beeuni/sdk';
+import { useSession } from '@beeuni/sdk/react';
+```
+
+### Legacy aliases — do not use in new code
+
+`package.json` still declares about twenty more subpaths: `/turns`, `/files`,
+`/session`, `/session/url`, `/auth`, `/config`, `/api-client`,
+`/projects-client`, `/platform-client`, `/opencode-client`, `/opencode-errors`,
+`/event-stream`, `/feature-flags`, `/fresh-sessions`, `/instance-routes`,
+`/message-queue`, and the un-prefixed store aliases.
+
+Every one of them is a one-line `export *` re-export under `src/deprecated/`,
+kept alive only so an existing `npm install` does not break. **They add nothing
+the root does not already export.** They are removed at the next major; new
+code imports the root.
+
+## Configuration
+
+`configureBeeuni(config)` (called for you by `createBeeuni`) wires one seam:
+
+```ts
+interface BeeuniPlatformConfig {
+  backendUrl: string;
+  getToken: () => Promise<string | null>;
+  /** @deprecated Inert: the SDK sends no client label. */
+  clientSource?: 'api' | 'cli' | 'mobile' | 'tui' | 'web';
+  clientVersion?: string; // '<surface>/<version>', sent as X-Beeuni-Client-Version
+  getUserId?: () => Promise<string | null>;
+  billingEnabled?: boolean;
+  sandboxId?: string | null;
+  onError?: (error: unknown, context?: unknown) => void;
+  onToast?: (level, message, options?) => void;
+  onNotify?: (event) => void;
+  featureFlags?: BeeuniFeatureFlagOverrides; // per-flag overrides for non-Next.js hosts
+}
+```
+
+`clientSource` is deprecated and inert. The audit log records what the API
+authenticated (`credential_kind`: browser session, personal access token,
+connected app, agent session, API key, service account), never a label the
+client reports about itself.
+
+Set `clientVersion` to the host's surface and release version, for example
+`cli/0.13.42`. The SDK sends it as `X-Beeuni-Client-Version` on every request.
+The API writes it to its request log only, so a route is retired only when no
+supported client version still calls it. It is telemetry: it never reaches the
+audit log and grants nothing. A blank value sends nothing.
+
+The SDK is host-agnostic: no Next.js / web coupling in the core. The host injects
+its token getter and toast/notify sinks; the SDK does the rest. Today that's proven
+in React DOM (`apps/web` and the `apps/whitelabel-demo` reference app are the
+`configureBeeuni`/`@beeuni/sdk/react` consumers).
+The framework-free core — turn classification, session URLs and health, the
+REST clients, file operations, transcript formatting — has no React or DOM
+dependency and is usable from any JS host, all of it from the root entry;
+`apps/mobile` imports `classifyTurn` from `@beeuni/sdk` this way.
+`apps/mobile` (React Native) also runs `useSession` from `@beeuni/sdk/react`.
+Its only platform code for the session runtime is the event transport
+(`eventStreamTransport`, `react-native-sse`) and the lifecycle signals
+(`notifyHostSignal` from `AppState` and its network listener).
+
+## Rules of the road
+
+- **No harness SDK in host code.** Import transcript and runtime types from
+  `@beeuni/sdk`, and reach the runtime through the session verbs. `session.runtime`
+  (the raw REST compatibility client) is deprecated.
+  (Holds today — no host imports `@opencode-ai/sdk`, and neither does the SDK.)
+- **No raw `backendApi` / `authenticatedFetch` in host code.** Use the facade or a
+  subpath module. (Aspirational: apps/web still calls `backendApi` via its
+  `@/lib/api-client` re-export in ~30 files and keeps a parallel
+  `authenticatedFetch` in `apps/web/src/lib/auth-token.ts` — migration pending.)
+- **React data** comes from `@beeuni/sdk/react` hooks; **imperative actions** from
+  the `createBeeuni` facade.
+
+## Auth
+
+`Authorization: Bearer <token>` — a Supabase JWT (user sessions), a Beeuni PAT
+(`beeuni_pat_…`) for server-side / automation use, or an OAuth access token
+(`beeuni_oat_…`) minted by "Sign in with Beeuni" — supplied via `getToken`.
+
+To use Beeuni from an MCP client (Claude, ChatGPT, Cursor, Codex) instead of code, see the hosted MCP server: <https://beeuni.ai/docs/connect/mcp>.
+
+### Sign in with Beeuni (your app, their Beeuni account)
+
+Make Beeuni the identity provider for an app you run. Register the app once
+(`beeuni.iam.oauthClients.create`, or Account → Tokens → OAuth apps), then:
+
+```ts
+import { createBeeuniAuth } from '@beeuni/sdk/server';
+
+export const auth = createBeeuniAuth({
+  backendUrl: 'https://api.beeuni.ai/v1',
+  clientId: process.env.BEEUNI_OAUTH_CLIENT_ID!,
+  clientSecret: process.env.BEEUNI_OAUTH_CLIENT_SECRET,   // omit for a public (PKCE-only) client
+  redirectUri: 'https://app.example.com/api/beeuni/auth/callback',
+  cookieSecret: process.env.BEEUNI_AUTH_COOKIE_SECRET!,   // ≥ 32 chars
+});
+
+// one catch-all route: /signin /callback /refresh /signout /me /proxy/*
+export const GET = (req: Request) => auth.handler(req);
+export const POST = GET;
+
+// anywhere on the server
+const gate = await auth.requireViewer(req);        // { viewer } | { response: 302 }
+const beeuni = await auth.beeuni(req);             // acts as the viewer
+// in the browser
+const client = createBeeuni(auth.clientConfig());  // talks to Beeuni through /proxy
+```
+
+`@beeuni/sdk/react` adds `useBeeuniViewer()` and `<SignInWithBeeuni />`.
+Full guide: `/docs/sdk/sign-in`. Example: `examples/11-sign-in-with-beeuni.ts`.
+
+### A Beeuni-hosted App is already signed in
+
+```ts
+const beeuni = createBeeuni({ backendUrl: '/_beeuni/api/v1', getToken: beeuniAppViewerToken() });  // browser
+const viewer = await readAppViewer(request);                                    // server (@beeuni/sdk/server)
+const asViewer = await createAppViewerBeeuni(request, { backendUrl });          // act as them
+```
+
+The Apps gate authenticated the visitor before your App was served and signs
+their identity into every request; `viewer_token_scope` on the App's access
+policy decides whether the App also gets a token to act with. On the server,
+read it per request; in the browser, `beeuniAppViewerToken()` replaces a token
+the API refused (after an access-policy change) and replays the call once.
+In the browser, `backendUrl` is `/_beeuni/api/v1`: the gate on the App's own
+origin forwards to the Beeuni API as the viewer (`viewer_token_scope: 'api'`).
+A direct call to `https://api.beeuni.ai/v1` from an App origin fails CORS.
+Guide: `/docs/sdk/apps`.
+
+### One member on every runtime: sign-in tokens, groups, roles
+
+```ts
+const db = beeuniBinding('db');                                                  // an App this App uses, same origin
+convex = new ConvexReactClient(db.url); convex.setAuth(db.token);                // its client, signed in as the viewer
+const token = await beeuniToken()();                                             // a token for this App itself
+const me = requireBeeuniMember(await ctx.auth.getUserIdentity(), { groups: ['Finance'] });  // a server function
+const caller = await verifyBeeuniToken(bearer);                                  // a server App (Beeuni injects BEEUNI_AUTH_*)
+const viewer = readBeeuniMember(await fetchBeeuniAppViewer());                   // browser
+```
+
+One issuer per project signs every App's tokens: `iss` =
+`<API origin>/v1/projects/<projectId>`, `aud` = the App id, 15 minutes. Every
+App JSON carries the values that verify them: `auth.issuer`, `auth.audience`,
+`auth.jwks_uri`. `beeuniToken({ audience })` asks the App's own origin
+(`/_beeuni/token`) for a token for the App itself or an App it uses (`uses`);
+any other App yields `null` and warns (`403 app_not_linked`). `beeuniBinding(slug)`
+reaches a used App's endpoint through `/_beeuni/apps/<slug>` on the same origin.
+`readBeeuniMember` reads every shape Beeuni vouches with (gate answer, signed
+header, sign-in token) into one `BeeuniMember`: `userId`, `email`, `name`,
+`picture`, `groups`, `groupIds`, `role`, `accountId`, `projectId`.
+`requireBeeuniMember` throws `BeeuniMemberError` (`unauthenticated` |
+`forbidden`). In React, read the member with a `members:me` query (`readBeeuniMember(await ctx.auth.getUserIdentity())` in `convex/members.ts`, then `useQuery(api.members.me)`: `undefined` loading, `null` signed out). Never call `useConvexAuth()`: it throws under a plain `ConvexProvider`. Beeuni injects `BEEUNI_AUTH_ISSUER`, `BEEUNI_AUTH_AUDIENCE` (the App's own id) and `BEEUNI_AUTH_JWKS` into every server App, so do not set `BEEUNI_AUTH_*` in its `env`. `verifyBeeuniToken` takes the key set inline or as an https URL
+(`auth.jwks_uri`), and refuses every token when no audience is set (option or
+`BEEUNI_AUTH_AUDIENCE`): one project key signs every App's tokens, so `aud` is
+the only thing that keeps another App's token out. `audience: false` opts out. WebCrypto only; no dependency. Guide: `/docs/sdk/apps`.
+
+### Headless sign-in (your users, straight through the API)
+
+```ts
+const session = beeuni.auth.session({ storage });             // self-refreshing token store
+const { session: s, user } = await beeuni.auth.signInWithPassword({ email, password });
+await session.set(s, user);
+const asUser = createBeeuni({ backendUrl, getToken: session.getToken });
+```
+
+Also `signUp`, `sendMagicLink` + `verifyOtp`, `signInWithProvider` +
+`exchangeCode` (PKCE), `resetPassword`, `updatePassword`, `user`, `signOut` —
+all `/v1/auth/*`, no Supabase in the client. Guide: `/docs/sdk/auth`.
+
+## Tests
+
+```sh
+pnpm --filter @beeuni/sdk typecheck  # package + examples/ (examples/tsconfig.json)
+pnpm --filter @beeuni/sdk test   # facade, files, react hooks, turns, transcript, session url/health, projects-client domains
+```
+
+See **`API-MAP.md`** for the complete endpoint catalogue. It covers the Beeuni
+REST API and the session runtime's REST routes. See **`CHANGELOG.md`** for
+per-release changes.
+
+
+### Agent repository access
+
+Agent configuration accepts `repository_access?: boolean` (default `true`).
+Set `false` to run new sessions without the project repository or repository API access.
+Git, secret, connector, and tool permissions remain separate. Existing sessions retain their saved policy.
+`AgentConfigBlock.workspace` is deprecated. The SDK maps legacy `branch`/`runtime` to the boolean field.
+A legacy `read` write requires an explicit `repository_access` choice; it does not enable read-only repository access.
+
+
+### Project provider and model access
+
+```ts
+const policy = await beeuni.projects.modelAccess(projectId);
+await beeuni.projects.setModelAccess(projectId, {
+  target: 'provider', id: 'beeuni', enabled: false,
+});
+await beeuni.projects.setModelAccess(projectId, {
+  target: 'model', id: 'openai/gpt-5.5', enabled: false,
+});
+```
+
+`beeuni` identifies Beeuni Managed Models. Other provider IDs identify BYOK, Codex, or custom providers. Provider disable takes precedence over individual model choices. Each write changes one target and preserves credentials. Disabling the current project default or its provider returns `409 cannot_disable_default`; select another default first.
+
+`useModelAccess(projectId)` from `@beeuni/sdk/react` exposes the policy, write state, and `setEnabled(change)`. Successful writes refresh both picker caches. Rejected writes leave the displayed policy unchanged. The policy blocks gateway inference; legacy `setProjectModelEnablement` remains display-only. Native runtimes that bypass the gateway return `enforced: false`.
+
+### Pooled ChatGPT connections
+
+With the `pooled_provider_secrets` and `llm_gateway` project flags enabled, a
+member can create a named ChatGPT OAuth account resource:
+
+```ts
+const challenge = await beeuni.project(projectId).secrets.startProviderOAuth('openai', {
+  resourceLabel: 'My ChatGPT account',
+});
+// Show challenge.verification_url and challenge.user_code, then poll the flow.
+const result = await beeuni.project(projectId).secrets.pollProviderOAuth('openai', challenge.flow_id);
+```
+
+Poll until `result.status` is `success`, `failed`, or `expired`. A successful
+named flow returns `credential.secret_id`. It creates a separate project-scoped
+account resource; reconnecting does not replace another account. Every project
+member can use it by default. The owner can restrict access to selected members.
+A session can select one or more available
+ChatGPT resources through its provider secret pool (`providerId: 'codex'`).
+Without an explicit session selection, the caller's newest personal ChatGPT
+resource is used. The legacy project login remains the fallback when that
+caller has no personal resource.
+
+### ChatGPT subscription usage
+
+`getSessionCost` and `getTurnCost` report zero LLM cost for ChatGPT/Codex
+subscription messages. This also corrects historical runtime costs. Token
+counts remain available. Mixed sessions retain paid API costs; OpenAI API
+models remain billable. Subscription coverage does not include sandbox compute.
+
+### Durable prompt placement
+
+`createSessionPrompt` and `useSessionPrompts().enqueue` accept an optional
+`placement: 'transcript' | 'composer'`. `transcript` (Quick Queue) runs before
+every `composer` (Queue List) entry and ends the active response after its
+current tool call. `composer` waits for the active response to finish. Each
+placement keeps submission order. A row without placement keeps its submission
+order ahead of `composer` entries and is presented as `composer`.
+
+### Prompt delivery: steer, queue, interrupt
+
+`createSessionPrompt` and `enqueue` also accept `delivery: 'steer' | 'queue' |
+'interrupt'`. It decides how a prompt reaches a running turn:
+
+- `steer`: the running turn reads the prompt at its next step boundary. The
+  turn does not stop.
+- `queue` (Queue List): the prompt waits for the turn to end.
+- `interrupt` (Quick Queue): the turn ends after its running tool, then the
+  prompt runs.
+
+With no turn running, every mode starts a turn. When only `delivery` is given,
+the SDK also sends the placement it implies (`interrupt` → `transcript`, the
+others → `composer`), so an API built before steering treats a steer prompt as
+a Queue List entry.
+
+A steer prompt falls back to `queue` when the runtime cannot take messages
+mid-turn, when another member's turn is running, or when the turn ended first.
+The row then reads `delivery: 'queue'` and `steer_fallback: 'unsupported' |
+'not_prompter' | 'turn_ended'`.
+
+`interruptSessionPrompt` (`session.prompts.interrupt`,
+`useSessionPrompts().interrupt`) is "Stop and send": it turns a row still
+waiting in the queue into Quick Queue. A row already on the wire answers `409`.
+
+`SessionPrompt.full_text` preserves complete text for rendering after reload;
+`text` remains the bounded preview. List responses expose attachment names and
+MIME types without attachment bytes. Removal responses retain the complete
+parts and captured model options for undo.
+
+Queued work keeps `useSessionWorking().state` at `working` so it can be stopped.
+`pendingDelivery: true` distinguishes a send waiting for runtime delivery from an
+active agent response. The web app still shows one working indicator whenever the
+session is `working`, so Stop is never the only sign of work.
+A timed-out or skipped cancel does not acknowledge an abort receipt.
+
+A worker claim only checks admission and keeps the prompt waiting. Delivery starts
+after admission succeeds. A confirmed active turn clears the pending presentation
+even if the previous inbox snapshot still lists that prompt. Runtime activity
+preserves the active turn's message ID during this handoff.
+
+Web sends Enter while a turn runs as **steer**, Command/Ctrl+Enter as **Queue
+List**, and "Stop and send" on a queued row as **Quick Queue**. Enter on an idle
+session starts a turn. Queued entries advance automatically; Quick Queue entries run first. Queue List entries stay editable
+until delivery begins. Stop pauses pending entries; Resume releases that hold.
+
+Pass the inbox IDs, in queue order, as `pendingMessageIds` to
+`groupMessagesIntoTurns(messages, { pendingMessageIds })`. Client-minted wire
+IDs still represent waiting prompts. The renderer keeps them after delivered
+turns until the inbox releases them.
+
+Queue acceptance and runtime execution are separate states. Each distinct submission
+appears immediately, including while a previous POST is pending. The working hook
+updates `pendingDelivery` when the same turn becomes active, without waiting for
+a different turn ID or timestamp.
+
+`useSessionPrompts` reads queue changes from the session's control stream
+(`GET .../sessions/:id/events?channels=control`, one connection per session per
+client). Every write of an inbox row arrives as a `beeuni.control.queue` frame,
+whichever API replica served the write. The `GET .../prompts` poll runs only
+while that stream is not connected, and a reconnect reads the list once.
+
+
+### Why a turn ended
+
+The transcript of an interrupted turn only carries `MessageAbortedError`. The
+control plane records the cause the sandbox reported, for example
+`SandboxMemoryGuard` when box memory passed its guard threshold, in
+`session_turns.end_error`. A stop somebody asked for is recorded there too, as a
+request (`UserStop` for a client abort, `QueueInterrupt` for a prompt sent into a
+busy session), and a request is never reported as a failure.
+
+`GET .../turn` returns the cause in `last_ended.error` and lists the turns that
+died in `recent_failures`, keyed by `message_id`, whether or not a turn is
+running: named causes, and failures with `error: null` when nobody named one.
+`useSessionTurnOutcome(projectId, sessionId)` reads both, plus the read time
+`atMs`, from the cache `useSessionWorking()` keeps fresh and makes no request of
+its own. `turnEndNotice(outcome, messageId, transcript)` turns that into one
+typed notice per turn — `sandbox-memory`, `cause`, `unexplained`, or `null` — so
+a host maps a kind to copy and never parses the sandbox's message.
+`turnEndCause(outcome, messageId)` returns the raw recorded cause.
+
+### External directory freshness
+
+`contract('directory')` from `@beeuni/sdk/react` refreshes mounted group and
+member queries every 10 seconds while the tab is visible. It also refreshes on
+focus and reconnect, including data still inside the stale-time window. It does
+not poll background tabs or change the identity provider's provisioning schedule.
+Other freshness tiers keep their existing behavior.