xapi-to 0.1.20 → 0.1.22

package/skills/xapi/guides/provider.md

@@ -0,0 +1,228 @@
+# Provider service management
+
+Read this guide for provider-side service authoring and operations. These
+commands use `XAPI-KEY` directly and never exchange it for a broad JWT session.
+The key must belong to the service owner and carry the scope named by the
+operation.
+
+## Inspect capabilities and scopes
+
+```bash
+npx xapi-to provider --help
+npx xapi-to skill --help
+npx xapi-to skill spec
+```
+
+Use narrowly scoped keys. Common scopes are:
+
+- `service:create`, `service:read`, `service:update`
+- `version:create`, `service:publish`, `service:rollback`
+- `observability:read`
+- `skill:read`, `skill:submit`
+- `earnings:read`; `earnings:transfer` only when reinvestment is intended
+- `service:delete` only for deliberate removal workflows
+
+Scope permission and ownership are independent. A key with a scope still cannot
+manage another provider's service or Skill.
+
+## Create and describe a service
+
+Create uses the backend service DTO as JSON so credentials and endpoint
+contracts do not have to appear in shell history:
+
+```bash
+npx xapi-to provider create --file ./service.json
+npx xapi-to provider list
+npx xapi-to provider get <service-id>
+```
+
+Keep the three service content layers distinct:
+
+- `description` is the short marketplace-card summary.
+- `aboutMarkdown` is the long About tab.
+- `website` is a public HTTP(S) link.
+
+Prefer files for long text:
+
+```bash
+npx xapi-to provider update <service-id> \
+  --description "Short marketplace summary" \
+  --about-file ./ABOUT.md \
+  --website https://example.com
+```
+
+Use `--clear-about` or `--clear-website` to clear a value. Provider metadata
+updates cannot modify the version contract or upstream credentials; use the
+version command for those fields.
+
+## Configure a service request limit
+
+Rate limits are optional service settings. Configure both values together when
+creating a service or updating an existing one:
+
+```bash
+npx xapi-to provider create --file ./service.json \
+  --rate-limit-requests 100 \
+  --rate-limit-period-seconds 60
+
+npx xapi-to provider update <service-id> \
+  --rate-limit-requests 100 \
+  --rate-limit-period-seconds 60
+```
+
+`requests` accepts 1 through 1,000,000 and `periodSeconds` accepts 1 through
+86,400. The backend applies one quota to each User x Service pair, so all API keys
+owned by the same user share that service quota. This setting is supported only
+for `PROXY` services; the backend rejects a non-null limit for `DIRECT` services.
+
+Disable the limit explicitly with:
+
+```bash
+npx xapi-to provider update <service-id> --clear-rate-limit
+```
+
+This sends `rateLimitConfig: null`. Omitting the rate-limit flags during an
+update leaves the existing setting unchanged. A raw `rateLimitConfig` can also
+be included in `service.json`; explicit CLI rate-limit flags override that field.
+
+## Edit and publish a revision
+
+```bash
+# Inspect current majors and revisions
+npx xapi-to provider versions <service-id>
+
+# Either create a new major or pull a working revision from an existing major
+npx xapi-to provider major create <service-id>
+npx xapi-to provider revision start <service-id> <major>
+
+# Merge a partial version-contract update; add --replace for full replacement
+npx xapi-to provider version update \
+  <service-id> <version-id> --file ./contract.json
+
+# Inspect before publishing
+npx xapi-to provider diff <service-id> <major>
+
+# Submit through the normal review gate with public release notes
+npx xapi-to provider publish \
+  <service-id> <revision-id> --changelog-file ./CHANGELOG.md
+
+# Inspect the review result
+npx xapi-to provider review <service-id> <revision-id>
+```
+
+The changelog is provider-authored, public release information associated with
+that revision. It is not a system deployment log. Build, review, and runtime
+events are generated by the platform and should only be read, never uploaded as
+if they were evidence.
+
+`publish` can change live service behavior after review. The CLI does not
+automatically retry this write after an ambiguous transport failure. Read the
+version overview and review state before deciding whether to submit again.
+
+## Create, upload, and link the usage Skill
+
+Generate a service-specific starting point from the currently serving endpoints:
+
+```bash
+npx xapi-to provider skill scaffold \
+  <service-id> --output ./my-service/SKILL.md
+```
+
+The scaffold command refuses to overwrite an existing file unless `--force` is
+explicitly supplied. Complete the instructions and metadata, then submit either
+a local directory or a public GitHub tree:
+
+```bash
+npx xapi-to skill submit --dir ./my-service
+
+npx xapi-to skill submit \
+  --github https://github.com/org/repo/tree/main/skills/my-service \
+  --version 1.0.0
+```
+
+Local submission skips symlinks, `.git`, and `node_modules`; requires a root
+`SKILL.md`; permits at most 100 files; limits each file to 512 KiB and the encoded
+package to 2 MiB. The server still performs manifest validation and secret
+scanning. A successful upload creates or updates the owned Skill version and
+submits it for review; it is not immediately public.
+
+Use the returned submission ID:
+
+```bash
+npx xapi-to skill status <submission-id>
+npx xapi-to skill wait <submission-id> --timeout 10m
+```
+
+After the Skill is published, bind it as the service's primary tutorial and
+record the serving-contract fingerprint:
+
+```bash
+npx xapi-to provider skill link <service-id> <skill-id>
+npx xapi-to provider skill fingerprint \
+  <service-id> --skill-version-id <skill-version-id>
+npx xapi-to provider skill context <service-id>
+```
+
+Only a Skill owned by the same provider can be linked, and one Skill can be the
+primary Skill of only one service. The backend permits linking a pending Skill,
+but the public marketplace exposes only a published version; wait for publication
+unless intentionally preparing the association early. Use `provider skill unlink`
+to remove the primary association. The context response reports drift when host,
+major version, or serving endpoints no longer match the stored fingerprint; update
+and resubmit the Skill rather than merely overwriting the fingerprint.
+
+## Observe and recover
+
+```bash
+npx xapi-to provider metrics --days 30
+npx xapi-to provider metrics <service-id> --days 7
+npx xapi-to provider events --limit 50
+npx xapi-to provider events --after '<opaque-next-cursor>' --limit 50
+```
+
+Pass event cursors back unchanged. Metrics and events are owner-scoped; usage
+events are also restricted to the current key where applicable.
+
+Verify the finalized cost of a canary or provider call with its receipt ID. Use
+the `X-XAPI-Request-Id` response header or the final `xapi.usage` SSE event, and
+wait when asynchronous billing has not finalized yet:
+
+```bash
+npx xapi-to usage <request-id>
+npx xapi-to usage wait <request-id> --timeout 1m
+```
+
+Receipt reads are idempotent. The wait command applies one total deadline,
+retries not-found and transient transport failures within that deadline, and
+fails immediately for permanent authorization or validation errors.
+
+Rollback and default-major changes affect live routing:
+
+```bash
+npx xapi-to provider rollback \
+  <service-id> <major> --revision <published-revision-id> \
+  --reason "Restore the last known-good contract"
+npx xapi-to provider default-major <service-id> <major>
+npx xapi-to provider deprecate <service-id> <major>
+npx xapi-to provider restore <service-id> <major>
+```
+
+Inspect the target revision before rollback. Do not automatically retry an
+ambiguous rollback response. Deletion requires both `service:delete` and an
+explicit service name or ID confirmation:
+
+```bash
+npx xapi-to provider delete <service-id> --confirm <service-name-or-id>
+```
+
+## Earnings reinvestment
+
+```bash
+npx xapi-to earnings
+npx xapi-to earnings list --status SETTLED
+npx xapi-to earnings transfer 1 --idempotency-key <stable-operation-key>
+```
+
+Transfer is one-way: it converts settled provider earnings into spendable xAPI
+balance. Confirm the amount and available settled balance first. A transfer may
+be retried only with the same idempotency key and the same amount.

package/skills/xapi/guides/sandbox.md

@@ -7,32 +7,45 @@ not an ordinary per-call action, so cleanup and audit are part of task success.
 
 ## Contents
 
+- [Product boundary](#product-boundary)
 - [Choose the shortest safe lifecycle](#choose-the-shortest-safe-lifecycle)
 - [Authentication and gateway selection](#authentication-and-gateway-selection)
 - [Inspect offerings and quote first](#inspect-offerings-and-quote-first)
 - [One-shot execution](#one-shot-execution)
-- [Multi-step agent lifecycle](#multi-step-agent-lifecycle)
+- [Multi-step client lifecycle](#multi-step-client-lifecycle)
 - [Files and artifacts](#files-and-artifacts)
 - [Web preview and background processes](#web-preview-and-background-processes)
 - [Suspend and resume](#suspend-and-resume)
 - [GPU jobs](#gpu-jobs)
-- [Parallel agents](#parallel-agents)
-- [OpenAI SandboxAgent with xAPI DeepSeek](#openai-sandboxagent-with-xapi-deepseek)
+- [Parallel isolated instances](#parallel-isolated-instances)
+- [OpenAI SandboxAgent integration example](#openai-sandboxagent-integration-example)
 - [Audit, history, and billing](#audit-history-and-billing)
-- [Run the real Playground acceptance suite](#run-the-real-playground-acceptance-suite)
+- [Run the real Playground recipe acceptance suite](#run-the-real-playground-recipe-acceptance-suite)
 - [Failure and interruption recovery](#failure-and-interruption-recovery)
 - [AI operating rules](#ai-operating-rules)
 
+## Product boundary
+
+xAPI is the Sandbox resource and capability provider. The CLI is a thin client
+for discovery, quote, lifecycle, exec, files, ports, provider extensions,
+history, audit, and billing. It does not implement prompts, model loops, memory,
+multi-agent orchestration, job DAGs, queues, or human approval workflows.
+
+Agent, CI, browser, and data examples in this guide are client-side recipes that
+compose Sandbox primitives. They are not additional Gateway workflow APIs.
+Provider-native features remain valid Sandbox extensions when the live Offering
+declares their schemas, limits, state effects, and billing behavior.
+
 ## Choose the shortest safe lifecycle
 
-| Need | Preferred command | Cleanup behavior |
-|---|---|---|
-| Run one command and get stdout | `sandbox run` | Terminates automatically |
-| Several exec/file calls | `create` + primitives | Agent must terminate |
-| Inspect price/capabilities | `offerings`, `quote` | No instance created |
-| Publish a temporary port | `port` after starting a server | Terminate afterward |
-| Pause a reusable workspace | `suspend` | Storage may keep billing |
-| Inspect prior work/cost | `history`, `get`, `audit` | Read-only |
+| Need                           | Preferred command              | Cleanup behavior         |
+| ------------------------------ | ------------------------------ | ------------------------ |
+| Run one command and get stdout | `sandbox run`                  | Terminates automatically |
+| Several exec/file calls        | `create` + primitives          | Agent must terminate     |
+| Inspect price/capabilities     | `offerings`, `quote`           | No instance created      |
+| Publish a temporary port       | `port` after starting a server | Terminate afterward      |
+| Pause a reusable workspace     | `suspend`                      | Storage may keep billing |
+| Inspect prior work/cost        | `history`, `get`, `audit`      | Read-only                |
 
 Prefer `sandbox run` whenever the task fits one remote shell command. A shorter
 lifecycle reduces orphan risk and returns one machine-readable JSON result.
@@ -79,6 +92,7 @@ npx xapi-to sandbox quote \
   --capabilities exec,files \
   --cpu 2 \
   --memory 4 \
+  --min-runtime 24h \
   --max-hourly-usd 0.20 \
   --format pretty
 ```
@@ -121,9 +135,9 @@ shells and AI runners can detect failure without parsing stdout.
 `--keep` suppresses automatic termination. Use it only after the user explicitly
 asks to retain the instance and understands that billing continues.
 
-## Multi-step agent lifecycle
+## Multi-step client lifecycle
 
-Use granular commands when an agent must alternate between files and commands.
+Use granular commands when a client must alternate between files and commands.
 Capture the instance ID without logging credentials:
 
 ```bash
@@ -205,15 +219,17 @@ port response contains `headers`, include them in external requests; they can
 carry a provider preview token. Do not emulate this mode with `nohup ... &` on
 an Offering that does not declare `backgroundExec`.
 
-Cloudflare currently uses its provider-specific command/preview behavior rather
-than the standard background session capability. Pin `cf-edge` only when the
-user explicitly wants Cloudflare. Port `8080` is the currently verified preview
-path for the deployed bridge:
+Cloudflare declares the standard background command surface and maps it to its
+native managed process API. Pin `cf-edge` only when the user explicitly wants
+Cloudflare. For a one-day workspace, require `--min-runtime 24h` and explicitly
+enable `cloudflare.set_keep_alive`; the runtime requirement filters offerings,
+while keepAlive prevents the default ten-minute idle reset:
 
 ```bash
 box_json="$(npx xapi-to sandbox create \
   --provider cf-edge \
-  --capabilities exec,files,ports \
+  --capabilities exec,backgroundExec,files,ports,lifecycle.keep_alive \
+  --min-runtime 24h \
   --wait)"
 box_id="$(printf '%s' "$box_json" | jq -r '.id')"
 port=8080
@@ -225,11 +241,11 @@ npx xapi-to sandbox file write "$box_id" index.html \
   --provider cf-edge \
   --content '<!doctype html><h1>xAPI preview</h1>'
 
-npx xapi-to sandbox exec "$box_id" --provider cf-edge --command \
-  "nohup python3 -m http.server $port >/tmp/server.log 2>&1 & \
-   for i in 1 2 3 4 5 6 7 8 9 10; do \
-     curl -sf http://127.0.0.1:$port/ && exit 0; sleep 1; done; \
-   cat /tmp/server.log >&2; exit 1"
+npx xapi-to sandbox extension "$box_id" cloudflare.set_keep_alive \
+  --provider cf-edge --input '{"keepAlive":true}'
+
+npx xapi-to sandbox exec "$box_id" --provider cf-edge --background --command \
+  "python3 -m http.server $port --directory /workspace"
 
 npx xapi-to sandbox port "$box_id" "$port" --provider cf-edge
 ```
@@ -242,6 +258,37 @@ terminate instead of leaving the instance billing. The URL stops working after
 termination. Quick Tunnels are for previews; use a stable, supported named
 tunnel or application deployment for production traffic.
 
+Cloudflare extensions also expose managed process logs/readiness, persistent
+shell sessions, stateful Python/JavaScript/TypeScript code contexts, Git
+checkout, file-change cursors, bucket mounts, and R2 backup/restore. Inspect
+`capabilities.extensionIds` before calling them. A default idle reset starts a
+fresh container and does not retain files, processes, sessions, or interpreter
+state. `keepAlive` removes that idle cutoff but does not guarantee that platform
+maintenance can never restart the host. Use R2 backup or external storage for
+state that must survive restarts, disable keepAlive in `finally`, and terminate.
+
+If the Offering declares `cloudflare.browser.*`, Cloudflare Browser Run can be
+used through the same generic extension command. Prefer a Quick Action for
+read-only page understanding before paying for a multi-step browser session:
+
+```bash
+npx xapi-to sandbox extension "$box_id" cloudflare.browser.snapshot \
+  --provider cf-edge \
+  --input '{"url":"https://example.com/","formats":["screenshot","markdown","accessibilityTree"]}'
+
+npx xapi-to sandbox extension "$box_id" cloudflare.browser.automate \
+  --provider cf-edge \
+  --input '{"url":"https://demo.playwright.dev/todomvc/","actions":[{"type":"fill","selector":".new-todo","value":"xAPI task"},{"type":"press","selector":".new-todo","key":"Enter"}],"extract":[{"name":"todos","selector":".todo-list li label","all":true}],"screenshot":{"type":"png","fullPage":true}}'
+```
+
+Browser Run and the Sandbox container do not share a filesystem. Write the
+returned page data into the sandbox through `sandbox file write` if a later
+container command must analyze it. Browser operations have separate operation
+prices; inspect the quote instead of assuming the container hourly cap includes
+them. The current automation extension is one-shot and closes the browser.
+Persistent CDP/Live View/HITL are not supported until xAPI owns and authorizes
+the session and proxies its WebSocket without exposing Cloudflare credentials.
+
 ## Suspend and resume
 
 Check offering lifecycle fields first because not every provider supports an
@@ -290,58 +337,65 @@ npx xapi-to sandbox terminate <id> --provider runpod
 GPU work is usually more expensive. Quote first, set a deliberate ceiling, use
 a command timeout, and terminate immediately after artifacts are retrieved.
 
-## Parallel agents
+## Parallel isolated instances
 
-Give each agent a separate instance. Do not share a mutable workspace when the
-goal is isolation. Use unique idempotency keys and record every instance ID.
+Give each concurrent worker or agent a separate instance. Do not share a mutable
+workspace when the goal is isolation. Use unique idempotency keys and record every instance ID.
 Run cleanup for all IDs even if one agent fails; then verify `sandbox list` has
 no active instance from the job.
 
 Limit concurrency based on budget. Parallel creation multiplies reservation and
 running cost, even when the individual hourly quote is small.
 
-## OpenAI SandboxAgent with xAPI DeepSeek
+## OpenAI SandboxAgent integration example
 
 The OpenAI Agents SDK keeps the model provider and sandbox provider separate.
 Use the SDK's OpenAI-compatible model provider for DeepSeek through
 `https://ai.xapi.to/v1`, and the xAPI adapter for Sandbox compute:
 
+The Agents SDK owns the model loop, tool choice, prompt, and conversation state.
+xAPI owns only the Sandbox resource, execution, lifecycle, audit, and billing.
+
 ```ts
-import { OpenAIProvider, Runner } from '@openai/agents';
-import { Manifest, SandboxAgent, shell } from '@openai/agents/sandbox';
-import { XapiAgentsSandboxClient } from 'xapi-to/openai-sandbox';
+import { OpenAIProvider, Runner } from "@openai/agents";
+import { Manifest, SandboxAgent, shell } from "@openai/agents/sandbox";
+import { XapiAgentsSandboxClient } from "xapi-to/openai-sandbox";
 
 const sandboxApiKey = process.env.XAPI_SANDBOX_KEY;
 const aiApiKey = process.env.XAPI_AI_KEY;
-if (!sandboxApiKey) throw new Error('XAPI_SANDBOX_KEY is required');
-if (!aiApiKey) throw new Error('XAPI_AI_KEY is required');
+if (!sandboxApiKey) throw new Error("XAPI_SANDBOX_KEY is required");
+if (!aiApiKey) throw new Error("XAPI_AI_KEY is required");
 
 const sandbox = new XapiAgentsSandboxClient({
   apiKey: sandboxApiKey,
-  sandboxHost: 'sandbox.test.xapi.to',
-  provider: 'daytona',
-  model: 'deepseek-v4-pro',
+  sandboxHost: "sandbox.test.xapi.to",
+  provider: "daytona",
+  model: "deepseek-v4-pro",
 });
 const modelProvider = new OpenAIProvider({
   apiKey: aiApiKey,
-  baseURL: 'https://ai.xapi.to/v1',
+  baseURL: "https://ai.xapi.to/v1",
   useResponses: false,
   strictFeatureValidation: true,
 });
 const runner = new Runner({ modelProvider, tracingDisabled: true });
 const agent = new SandboxAgent({
-  name: 'xAPI DeepSeek sandbox agent',
-  model: 'deepseek-v4-pro',
+  name: "xAPI DeepSeek sandbox agent",
+  model: "deepseek-v4-pro",
   defaultManifest: new Manifest({ root: sandbox.workspaceRoot }),
   capabilities: [shell()],
-  instructions: 'Use shell to complete and verify the task.',
+  instructions: "Use shell to complete and verify the task.",
 });
 
 try {
-  const result = await runner.run(agent, 'Write SDK_OK=42 to result.txt and read it.', {
-    maxTurns: 8,
-    sandbox: { client: sandbox },
-  });
+  const result = await runner.run(
+    agent,
+    "Write SDK_OK=42 to result.txt and read it.",
+    {
+      maxTurns: 8,
+      sandbox: { client: sandbox },
+    },
+  );
   console.log(result.finalOutput);
 } finally {
   await sandbox.lastSession?.close();
@@ -406,9 +460,9 @@ For acceptance, verify:
 
 Use the returned billing data rather than recomputing cost from wall-clock time.
 
-## Run the real Playground acceptance suite
+## Run the real Playground recipe acceptance suite
 
-From an xapi-cli development checkout, run the same nine real workflows shown
+From an xapi-cli development checkout, run the same nine client recipes shown
 in the Web Playground. The suite uses normal CLI configuration, never accepts a
 key on argv, records audit/billing evidence, terminates every tracked instance
 in `finally`, and fails if any instance created after its baseline remains

package/skills/xapi/guides/ws_gateway.md

@@ -1,6 +1,6 @@
 # WebSocket Gateway Guide
 
-Use xAPI's WebSocket Gateway for full-duplex, low-latency sessions such as OpenAI Realtime, streaming speech recognition, bidirectional text-to-speech, simultaneous interpretation, and podcast generation.
+Use xAPI's WebSocket Gateway for full-duplex, low-latency sessions such as GPT Live, OpenAI Realtime, streaming speech recognition, bidirectional text-to-speech, simultaneous interpretation, and podcast generation.
 
 The WebSocket Gateway shares the public `ai.xapi.to` host with the HTTP AI Gateway, but it is a separate protocol surface. An HTTP request continues to use the AI Gateway; a valid WebSocket Upgrade request is routed to the WebSocket Gateway.
 
@@ -9,6 +9,7 @@ The WebSocket Gateway shares the public `ai.xapi.to` host with the HTTP AI Gatew
 - [Choose the right interface](#choose-the-right-interface)
 - [Public URLs and routing](#public-urls-and-routing)
 - [Authentication](#authentication)
+- [GPT Live example](#gpt-live-example)
 - [OpenAI Realtime example](#openai-realtime-example)
 - [Browser connections](#browser-connections)
 - [Native protocol endpoints](#native-protocol-endpoints)
@@ -39,6 +40,7 @@ Current curated production paths include:
 
 | Path | Protocol | Typical use |
 |---|---|---|
+| `/v1/live/sessions` on the GPT Live service host | OpenAI Live Sessions JSON events | GPT-Live 1 voice with Client or managed Responses delegation |
 | `/v1/realtime` | OpenAI Realtime GA JSON events | Realtime text and voice |
 | `/v1/asr` | Volcengine ASR binary frames | Streaming speech recognition |
 | `/v1/tts` | Doubao bidirectional TTS binary frames | Streaming text-to-speech |
@@ -57,6 +59,15 @@ wss://<service-slug>.p.xapi.to/<endpoint-path>
 
 This avoids shared-path ambiguity and is required when the desired service uses a provider-native protocol that is not selected by the unified path. Console Try-It and review workflows can also address an endpoint exactly with `?endpoint=<endpoint-id>`.
 
+GPT Live currently uses the service-specific URL:
+
+```text
+wss://openai-live.p.xapi.to/v1/live/sessions
+```
+
+Do not replace it with `/v1/realtime`. Live Sessions uses `session.start` and
+`session.started`; Realtime uses a different session lifecycle and event model.
+
 ## Authentication
 
 Use the same xAPI key as the CLI and HTTP Gateway. Server-side clients should send one of these handshake headers:
@@ -78,6 +89,43 @@ The Gateway also accepts `?token=<XAPI_KEY>` or `?xapi-key=<XAPI_KEY>` for clien
 
 Authentication is checked before the WebSocket upgrade. Invalid handshakes therefore return an HTTP status instead of opening and immediately closing a socket.
 
+## GPT Live example
+
+GPT Live is a provider-native JSON event protocol, not an Action `call` and not
+OpenAI Realtime. The first client frame must be `session.start`. The production
+endpoint locks the Live model to `gpt-live-1`, disables storage, and lets the
+caller choose `client` or `responses` delegation once per connection. In
+`responses` mode, the managed Responses model and its limits remain
+server-controlled.
+
+The packaged `examples/openai-gpt-live-text.mjs` demonstrates the smallest
+managed-Responses lifecycle: connect with a server-side xAPI key, send
+`session.start`, wait for `session.started`, create a text item, request a
+response, and finish with `session.close` after the nested response completes.
+It intentionally omits microphone capture so the protocol boundary is clear.
+
+```bash
+# Install the example's WebSocket transport in your application directory.
+npm install ws
+
+# Supply XAPI_KEY through the process environment; never put it in source code
+# or pass it as a command-line argument.
+node examples/openai-gpt-live-text.mjs "Answer in one short sentence."
+```
+
+Voice clients use the same session lifecycle, then send base64 PCM chunks as
+`session.input_audio.append` events and consume `session.output_audio.delta`.
+Audio format, voice, interruption behavior, and the complete event schema must
+follow the current Live Sessions contract. Do not copy Realtime
+`conversation.item.create` or `input_audio_buffer.*` events into a Live session.
+
+With `client` delegation, the application must handle
+`session.delegation.created`, run its own text-model request, and return the
+result with `session.commentary.append`, then wait for
+`session.commentary.appended`. Selecting `client` does not make xAPI run a
+model on the application's behalf. Use `responses` when the managed backend is
+desired.
+
 ## OpenAI Realtime example
 
 The unified `/v1/realtime` route speaks the OpenAI Realtime GA JSON event protocol. It is native passthrough: send the same events you would send to the upstream Realtime API, but authenticate with the xAPI key.
@@ -121,15 +169,26 @@ Do not send the retired `OpenAI-Beta: realtime=v1` header. Session settings, aud
 The browser `WebSocket` API cannot set arbitrary handshake headers. The Gateway accepts an xAPI key or temporary token through a subprotocol entry:
 
 ```javascript
-const temporaryToken = await getTemporaryTokenFromYourBackend();
+const credential = await getEndpointBoundCredentialFromYourBackend(endpointId);
+if (Date.now() >= new Date(credential.latestStartAt).getTime()) {
+  throw new Error("refresh the credential before opening a full new session");
+}
 const ws = new WebSocket(
-  "wss://ai.xapi.to/v1/realtime",
-  [`xapi-key.${temporaryToken}`],
+  "wss://openai-live.p.xapi.to/v1/live/sessions",
+  ["xapi-ws-v1", `xapi-key.${credential.token}`],
 );
 ```
 
 Never embed a long-lived xAPI key in frontend JavaScript. Use the authenticated xAPI Console Try-It flow or your backend to obtain a short-lived token, then pass only that token to the browser. The Console's `POST /api/keys/ws-token` flow mints a temporary token for a WebSocket endpoint; it requires a logged-in entity account and an endpoint ID, and is not authenticated with a normal xAPI key.
 
+The credential is endpoint-bound and returns `expiresAt`, `latestStartAt`, and
+`maxDurationSec`. It may be reused for reconnects only while the new connection
+starts before `latestStartAt`; after that boundary, mint a fresh credential so
+the full advertised session and final `session.close` exchange fit inside its
+lifetime. If an endpoint declares public subprotocols, retain them and append
+the `xapi-key.*` entry; otherwise use the non-secret `xapi-ws-v1` marker shown
+above. Never log the secret subprotocol value.
+
 If a browser integration must use `?token=`, use only a short-lived token and avoid logging the complete URL.
 
 ## Native protocol endpoints
@@ -138,6 +197,7 @@ The Gateway forwards frames without translating the application protocol. The se
 
 | Adapter | Client frames | Important client requirement |
 |---|---|---|
+| `openai-live` | UTF-8 JSON text | First frame is `session.start`; choose Client or managed Responses delegation once. |
 | `openai-realtime` | UTF-8 JSON text | Use OpenAI Realtime GA events. |
 | `volcengine-asr` | Binary | Send the Volcengine ASR header/config/audio frame sequence; PCM configuration must match the audio bytes. |
 | `doubao-realtime` | Binary | Use the Doubao end-to-end realtime dialogue protocol through its service host or exact endpoint. |