xapi-to 0.1.19 → 0.1.20

package/skills/xapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xapi
-description: Access real-time external data via the xapi CLI — Twitter/X (including resolving and downloading tweet videos), Douyin/TikTok, Reddit, LinkedIn, Weibo, on-chain crypto data (price, holders, wallets, DEX, CEX), web/news/image/video/scholar search, AI text/image/video/speech generation and transcription, and SMS verification. Configure the Anthropic/OpenAI-compatible xAPI AI Gateway or the xAPI WebSocket Gateway for realtime voice, streaming ASR/TTS, and provider-native bidirectional sessions. Use when the user mentions xapi, wants to call a third-party API, asks what external services are available, or needs to connect an AI or realtime client to xAPI.
+description: Access real-time external data and managed cloud sandboxes via the xapi CLI — Twitter/X, social platforms, crypto, web/news search, AI generation, SMS verification, and auditable ephemeral compute. Configure the xAPI AI or WebSocket Gateways, or use sandbox run for automatic quote/create/execute/cleanup. Use when the user mentions xapi, external services, or sandbox compute.
 metadata: {"openclaw":{"emoji":"x","requires":{"anyBins":["npx"]},"primaryEnv":"XAPI_KEY"}}
 ---
 
@@ -62,6 +62,17 @@ xapi offers two types of APIs under a unified interface:
 
 Both types use the same discovery and call workflow. Use `--source capability` or `--source api` on commands that expose source filtering.
 
+## Managed Sandbox Compute
+Read `guides/sandbox.md` before creating a billable instance. For a one-shot
+command, prefer `sandbox run`; it quotes, applies a price ceiling, waits,
+executes, and terminates in `finally`:
+```bash
+npx xapi-to sandbox run --command 'python3 -c "print(6 * 7)"'
+```
+Use granular commands only for multi-step work. Keep the instance ID, terminate
+in cleanup, and verify terminal state/cost afterward. Do not use `--keep` unless
+the user explicitly wants a reusable, continuing-to-bill instance.
+
 ## Usage Workflow
 
 **Critical rule:** Before calling any API, always use `get` to understand the required parameters.
@@ -362,7 +373,7 @@ npx xapi-to call web.search --input '{"q":"hello world"}'
 npx xapi-to call serper.search --input '{"body":{"q":"hello world"}}'
 ```
 
-This ensures correct types (strings, numbers, booleans) are preserved.
+Read `guides/serper.md` before using direct `serper.*` actions; it covers all current v7 actions, mini-batches, Reviews, billing, and the `web.search.*` boundary.
 
 ## Code Generation (`--code`)
 
@@ -436,10 +447,10 @@ Beyond built-in capabilities, xapi proxies **dozens** of third-party API service
 - **Douyin** (`douyin`) — Douyin/TikTok API (videos, users, trending, comments)
 - **Twitter API** (`twitter`) — Alternative Twitter data API
 - **Reddit** (`reddit`) — Reddit API (posts, comments, subreddits, search)
-- **LinkedIn** (`linkedin`) — LinkedIn API (person profiles & career history, company pages, posts & comments, job search)
+- **LinkedIn** (`linkedin`) — LinkedIn API (person profiles & career history, company pages, posts & comments, job search). For career history, see `guides/linkedin.md` first — the profile endpoint silently omits `experience`/`education` for ordinary profiles
 - **Weibo** (`weibo-app`) — Weibo API (user profiles, feeds, search, trending)
 - **5SIM SMS** (`5sim-sms`) — SMS verification (virtual numbers, activation codes)
-- **Serper API** (`serper`) — Google Search API
+- **Serper API** (`serper`) — 12 provider-native Google Search actions including web, images, news, maps, places, video, shopping, scholar, patents, autocomplete, Lens, and reviews. Eleven support mini-batch; Reviews does not. Read `guides/serper.md` before calling them
 - **OpenRouter API** (`openrouter`) — Multi-model AI gateway (chat, embeddings, audio transcription/speech, video)
 
 The full catalog also spans many other categories — crypto/on-chain data, CEX market data, stocks & macro, social platforms, news, weather, and more. Discover them with `search` / `services`.
@@ -465,16 +476,18 @@ When the user's task involves these workflows, read the corresponding guide file
 
 - **`guides/twitter.md`** — Twitter/X (推特): read and paginate tweets/replies/media, download the highest-quality MP4 from a video tweet, advanced search, read long-form X Articles directly from `tweet_detail`, post tweets, reply, quote, like, retweet, OAuth binding
 - **`guides/reddit.md`** — Reddit: user profiles, posts, comments, subreddit feeds, popular/news/games feeds, trending, search
-- **`guides/linkedin.md`** — LinkedIn (领英): person profiles with career history, company pages, posts & comments, job search & job detail — every endpoint but job search is addressed by an ordinary LinkedIn page URL, and post comments need a numeric `urn` alongside `url`
+- **`guides/linkedin.md`** — LinkedIn (领英): person profiles with career history, company pages, posts & comments, job search & job detail — every endpoint but job search is addressed by an ordinary LinkedIn page URL, and post comments need a numeric `urn` alongside `url`. **Read this guide before summarizing anyone's background:** `get__user__profile` returns `experience: null` / `education: null` for ordinary (non-creator) profiles because it reads the logged-out page, and the guide gives the fallback that recovers the real career history
 - **`guides/tiktok.md`** — TikTok: user profiles, videos, comments, search, hashtags, music, live rooms, feed
 - **`guides/douyin.md`** — Douyin (抖音): user profiles, videos, comments, hot search, hashtags, music, video mix/series
 - **`guides/xiaohongshu.md`** — 小红书 (Xiaohongshu): user profiles, notes, comments, search, topics, products, creator inspiration
 - **`guides/weibo.md`** — Weibo (微博): hot search, content search, user profiles, post details, comments, reposts, media
 - **`guides/google_search.md`** — Google Search: web, realtime, news, image, video, scholar, maps, places, shopping
+- **`guides/serper.md`** — direct Serper v7 API: 12 provider-native actions, object-or-array mini-batches, Reviews pagination and batch exception, Lens, dynamic per-credit billing, and the current Webpage service boundary
 - **`guides/crypto.md`** — Crypto (加密货币): on-chain token price/overview/holders/security/OHLCV, wallet analytics, DEX pairs, CEX spot prices by symbol, news — covers contract-address vs symbol addressing and multi-chain
 - **`guides/ai.md`** — AI (人工智能): synchronous or SSE-streamed text, embeddings, asynchronous image/video generation with `task wait`, text-to-speech, and speech-to-text
 - **`guides/ai_gateway.md`** — xAPI AI Gateway: Claude Code and Anthropic/OpenAI SDK setup, model discovery, routing strategies, streaming, fallback, routing/billing headers, direct media endpoints, and known limitations
 - **`guides/ws_gateway.md`** — xAPI WebSocket Gateway: OpenAI Realtime, streaming ASR/TTS, simultaneous interpretation, podcast generation, service/path routing, browser authentication, native binary protocols, limits, billing, close codes, and reconnects
+- **`guides/sandbox.md`** — managed Sandbox compute: AI tool selection, one-shot and multi-step lifecycles, provider pinning, files, Cloudflare Web previews, suspension, GPU jobs, parallel agents, cleanup recovery, audit/history, and billing verification
 - **`guides/sms.md`** — SMS verification: buy virtual phone numbers, receive verification codes, finish/cancel orders (5SIM)
 
 ## Security

package/skills/xapi/guides/linkedin.md

@@ -8,6 +8,7 @@ Complete guide for LinkedIn operations via xAPI — person profiles with career
 
 - [Key concept: everything is addressed by URL](#key-concept-everything-is-addressed-by-url)
 - [Person data](#person-data)
+  - [When `experience` and `education` come back `null`](#when-experience-and-education-come-back-null)
 - [Company data](#company-data)
 - [Posts and comments](#posts-and-comments)
 - [Jobs](#jobs)
@@ -56,6 +57,48 @@ One call returns the whole profile — no follow-up requests for individual sect
 
 There are no separate `get__user__experience` / `educations` / `skills` / `honors` / `publications` endpoints in v2 — that was the older `username` → `urn` two-step API. If you were using those IDs, they now return `Action not found`.
 
+### When `experience` and `education` come back `null`
+
+`get__user__profile` reads the **logged-out** public page. LinkedIn renders the full career and school sections there only for creator/open profiles; on an ordinary member's page it serves a trimmed topcard. The call still succeeds with `code: 200`, so the failure is silent — you get identity, `current_company`, `educations_details`, `followers`, and `people_also_viewed`, but:
+
+```json
+{ "position": null, "experience": null, "education": null, "about": "Don't use LinkedIn that much…" }
+```
+
+`null` here means **not rendered to logged-out visitors**, not "this person has no jobs listed". A truncated `about` ending in `…` is the same signal. Never summarize a person's background from a response in this state, and never report the profile as private or empty — fall back:
+
+```bash
+npx xapi-to call icypeas-email.api_scrape_profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/ricky-wang-74b3a0194/"}}'
+```
+
+This returns a differently-shaped payload under `data.result`:
+
+| Field | Contents |
+|---|---|
+| `worksFor[]` | Current positions — `jobTitle`, `startDate`, `description`, nested `company` (industry, size, website, HQ) |
+| `alumniOf[]` | Past positions — same shape plus `endDate` |
+| `educations[]` | `name`, `degree`, `fieldsOfStudy[]`, `description` |
+| `headline`, `description` | Headline and the full untruncated About text |
+| `firstname`, `lastname`, `address`, `numOfConnections`, `skills[]`, `languages[]` | Identity and profile detail |
+
+Check `data.status` before reading `data.result`: `FOUND` means real data, `NOT_FOUND` means `result` is `null` and this source has nothing for that URL either. Two caveats worth carrying into any summary: the snapshot is cached, so `headline` can lag the person's current role, and `startDate`/`endDate` are year-granular (often stamped to January), so treat them as approximate. `jobTitle` also reflects whatever the member typed, which can disagree with a company's own announcement — prefer cross-checking a role against `web.search` before asserting a title.
+
+Do not reach for `contactout-api.v1_linkedin_enrich` as a fallback. Without a separate ContactOut contract it returns a fully-populated **sample profile** (`"Example Person"` at `"Legros, Smitham and Kessler"`) with `status_code: 200`, which is easy to mistake for real data, and it is the most expensive LinkedIn-adjacent action in the catalog.
+
+### Person profile decision path
+
+```
+get__user__profile
+  ├─ experience[] present            → done, use it
+  └─ experience/education == null    → icypeas-email.api_scrape_profile
+        ├─ status == FOUND           → read worksFor / alumniOf / educations
+        └─ status == NOT_FOUND       → say the career history is unavailable;
+                                        fall back to web.search for public
+                                        bios, or twitter.user_by_screen_name
+                                        when the person came from an X handle
+```
+
 ### Get a person's posts
 
 ```bash
@@ -144,6 +187,10 @@ This is the most expensive LinkedIn endpoint — search first, then fetch detail
 npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__profile \
   --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/"}}'
 
+# 1b. Only if experience/education came back null — career history from the fallback
+npx xapi-to call icypeas-email.api_scrape_profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/"}}'
+
 # 2. Their posts (take `urn` from each item for step 3)
 npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__posts \
   --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/","page":1}}'
@@ -186,6 +233,12 @@ npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__company__profile \
 | `search__jobs` | Job search | `keywords` | `location`, `page` |
 | `get__job__detail` | Full job posting | `url` | — |
 
+One non-`linkedin` action belongs in this workflow:
+
+| Action ID | Purpose | Required params | Notes |
+|---|---|---|---|
+| `icypeas-email.api_scrape_profile` | Career history for profiles the logged-out page hides | `url` | Fallback when `get__user__profile` returns `experience: null`. Check `data.status == "FOUND"`. |
+
 Detail-style endpoints (`get__*__profile`, `get__post__detail`) are the cheapest; list-style endpoints (posts, comments, job search) cost more per call, and `get__job__detail` is the most expensive. Run `npx xapi-to get <action-id>` for the current `meta.pricing` rather than assuming these ratios hold.
 
 ## Error Handling
@@ -195,4 +248,6 @@ Detail-style endpoints (`get__*__profile`, `get__post__detail`) are the cheapest
 - **`must have required property 'urn'`** — `get__post__comments` needs the numeric `urn` alongside `url`. See [Get comments on a post](#get-comments-on-a-post).
 - **`must match pattern "^[0-9]+$"` on `/params/urn`** — you passed the prefixed `urn:li:activity:<id>` form. Send the digits only.
 - **`API Token lacks required permissions`** (upstream `403`) — the account's upstream provider token has no LinkedIn scope. This is an account entitlement, not a parameter problem; enable it in the provider dashboard.
+- **`experience: null` / `education: null` / `about` ending in `…` on `get__user__profile`** — not an error and not a private profile: the logged-out page LinkedIn serves for ordinary members omits those sections. Fall back to `icypeas-email.api_scrape_profile`. See [When `experience` and `education` come back `null`](#when-experience-and-education-come-back-null).
+- **A ContactOut response naming `Example Person` at `Legros, Smitham and Kessler`** — `contactout-api.*` returned its sample payload because the account has no ContactOut entitlement. It carries `status_code: 200` and a `message` pointing at a sales call. Discard it; never summarize from it.
 - **Empty `data[]` on a valid URL** — either the page is private/deleted, or you paginated past the end. LinkedIn also rate-limits aggressively; retry with backoff rather than in a tight loop.

package/skills/xapi/guides/sandbox.md

@@ -0,0 +1,466 @@
+# Managed Sandbox Compute Guide
+
+Use xAPI Sandbox when a user or AI agent needs an isolated cloud computer for
+code execution, file processing, CI reproduction, a temporary Web/API preview,
+GPU work, or a resumable multi-step job. It is a billable lifecycle service,
+not an ordinary per-call action, so cleanup and audit are part of task success.
+
+## Contents
+
+- [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)
+- [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)
+- [Audit, history, and billing](#audit-history-and-billing)
+- [Run the real Playground acceptance suite](#run-the-real-playground-acceptance-suite)
+- [Failure and interruption recovery](#failure-and-interruption-recovery)
+- [AI operating rules](#ai-operating-rules)
+
+## 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 |
+
+Prefer `sandbox run` whenever the task fits one remote shell command. A shorter
+lifecycle reduces orphan risk and returns one machine-readable JSON result.
+
+## Authentication and gateway selection
+
+The CLI reads `XAPI_KEY`, then `XAPI_API_KEY`, then `~/.xapi/config.json`.
+Do not print, interpolate into a URL, or pass the key inside the remote command.
+The CLI sends Sandbox credentials only to `*.xapi.to` or localhost.
+
+Production uses `sandbox.xapi.to`. The test service is selected explicitly:
+
+```bash
+export XAPI_SANDBOX_HOST=sandbox.test.xapi.to
+```
+
+Omit `--provider` (or use `--provider auto`) for lowest-price compatible
+selection. Pin only when the task or test requires a particular provider:
+
+```bash
+npx xapi-to sandbox offerings --provider cf-edge --format table
+npx xapi-to sandbox quote --provider daytona --capabilities exec,files
+```
+
+Provider pinning derives a controlled hostname such as
+`cf-edge.sandbox.test.xapi.to`; it does not accept arbitrary provider URLs.
+For production, canonical `--provider daytona` and `--provider e2b` are mapped
+to the deployed `daytona-sandbox.sandbox.xapi.to` and
+`e2b-sandbox.sandbox.xapi.to` aliases; their test hosts remain
+`daytona.sandbox.test.xapi.to` and `e2b.sandbox.test.xapi.to`.
+Available providers and capabilities can change, so inspect `offerings` rather
+than assuming a static capability matrix.
+
+## Inspect offerings and quote first
+
+`offerings` shows provider-declared resources, capabilities, lifecycle support,
+and hourly estimates. `quote` applies requirements without creating or billing
+an instance:
+
+```bash
+npx xapi-to sandbox offerings --format table
+
+npx xapi-to sandbox quote \
+  --capabilities exec,files \
+  --cpu 2 \
+  --memory 4 \
+  --max-hourly-usd 0.20 \
+  --format pretty
+```
+
+Use `--format table` for a compact comparison and JSON when a complete quote ID
+or nested rate card must be copied. Table truncation is marked with `…`.
+
+Use `--requirements '<json>'` for fields that do not have a shortcut. Treat
+`--max-hourly-usd` as a hard guardrail chosen before creation. A quote is
+short-lived; create promptly or quote again.
+
+## One-shot execution
+
+`sandbox run` performs quote → create → wait for `RUNNING` → exec → terminate →
+read final cost. Its default price ceiling is `$0.20/hour`:
+
+```bash
+npx xapi-to sandbox run \
+  --capabilities exec \
+  --command 'python3 -c "print(sum(range(1000)))"' \
+  --format pretty
+```
+
+Arguments after a bare `--` are joined into the remote command:
+
+```bash
+npx xapi-to sandbox run -- node --version
+```
+
+Read these output fields first:
+
+- `result.exitCode`, `result.stdout`, `result.stderr`: remote result;
+- `cleanup.operationStatus`, `cleanup.state`: teardown result;
+- `finalState`: should be `TERMINATED` (or provider-terminal `FAILED`);
+- `totalCost`: service-calculated cost, not a client estimate.
+
+A remote non-zero exit code becomes the local CLI exit code after cleanup, so
+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
+
+Use granular commands when an agent must alternate between files and commands.
+Capture the instance ID without logging credentials:
+
+```bash
+box_json="$(npx xapi-to sandbox create \
+  --capabilities exec,files \
+  --idempotency-key "job-${JOB_ID}" \
+  --wait)"
+box_id="$(printf '%s' "$box_json" | jq -r '.id')"
+
+npx xapi-to sandbox wait "$box_id" --state RUNNING --wait-timeout 5m
+
+cleanup() {
+  npx xapi-to sandbox terminate "$box_id" --wait-timeout 5m || true
+}
+trap cleanup EXIT INT TERM
+
+npx xapi-to sandbox file write "$box_id" task.md --file ./task.md
+npx xapi-to sandbox exec "$box_id" --command 'npm test' --timeout 120
+npx xapi-to sandbox file read "$box_id" report.json --output ./report.json
+```
+
+Use a stable business `--idempotency-key` when the caller might repeat create
+after a lost response. Do not blindly repeat mutations with a new key: the first
+request may already have created a billable instance.
+
+The CLI rejects unknown Sandbox flags before making a request. Exact
+`--offering-id` selection cannot be combined with `--max-hourly-usd`; select by
+requirements under a ceiling or create from a previously checked quote instead.
+Successful create output returns `clientIdempotencyKey`. If `create --wait`
+fails after acceptance, retain the structured `instanceId`, `observedState`,
+`clientIdempotencyKey`, and recovery commands from stderr, then inspect and
+terminate the instance as appropriate.
+
+## Files and artifacts
+
+Write inline text or a local file:
+
+```bash
+npx xapi-to sandbox file write <id> instructions.txt --content 'Run tests.'
+npx xapi-to sandbox file write <id> input.csv --file ./input.csv
+```
+
+Read and list artifacts:
+
+```bash
+npx xapi-to sandbox file list <id> --path . --depth 3
+npx xapi-to sandbox file read <id> output.json
+npx xapi-to sandbox file read <id> output.zip --output ./output.zip
+```
+
+Local `--output` uses create-new semantics and refuses to overwrite an existing
+file. The CLI base64-encodes local input bytes so binary files survive transfer.
+
+## Web preview and background processes
+
+For providers that declare both `backgroundExec` and `ports`, use the explicit
+provider-managed background command. Daytona needs this mode because deleting a
+foreground command session also kills shell-backgrounded child processes:
+
+```bash
+box_json="$(npx xapi-to sandbox create \
+  --provider daytona \
+  --capabilities exec,backgroundExec,ports \
+  --wait)"
+box_id="$(printf '%s' "$box_json" | jq -r '.id')"
+port=25319
+
+cleanup() { npx xapi-to sandbox terminate "$box_id" --provider daytona || true; }
+trap cleanup EXIT INT TERM
+
+npx xapi-to sandbox exec "$box_id" --provider daytona --background --command \
+  "python3 -m http.server $port --bind 0.0.0.0"
+npx xapi-to sandbox port "$box_id" "$port" --provider daytona
+```
+
+`--background` returning a session/command ID is only launch acknowledgement.
+Poll the public URL with bounded retries and verify an expected marker. If the
+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:
+
+```bash
+box_json="$(npx xapi-to sandbox create \
+  --provider cf-edge \
+  --capabilities exec,files,ports \
+  --wait)"
+box_id="$(printf '%s' "$box_json" | jq -r '.id')"
+port=8080
+
+cleanup() { npx xapi-to sandbox terminate "$box_id" --provider cf-edge || true; }
+trap cleanup EXIT INT TERM
+
+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 port "$box_id" "$port" --provider cf-edge
+```
+
+Validate that the returned public URL serves the expected marker before calling
+the workflow successful. Quick Tunnel DNS/TLS readiness can be intermittent, so
+use bounded retries (for example, one request every two seconds for up to two
+minutes). If it still fails, verify localhost again, record the URL/error, and
+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.
+
+## Suspend and resume
+
+Check offering lifecycle fields first because not every provider supports an
+explicit suspend operation:
+
+```bash
+npx xapi-to sandbox offerings --format pretty
+npx xapi-to sandbox suspend <id>
+npx xapi-to sandbox get <id>
+npx xapi-to sandbox resume <id>
+```
+
+The CLI waits for `SUSPENDED` and `RUNNING` by default. Files may persist while
+memory/processes do not; rely on the selected offering's declared lifecycle
+semantics. Suspension can reduce compute cost but storage may still accrue cost.
+If `lifecycle.suspension.supported` is false (as with a current cf-edge
+offering), do not call suspend/resume; terminate and create a new instance.
+
+## GPU jobs
+
+Request GPU resources instead of assuming a provider or model. The current
+RunPod offering is a managed GPU resource without standard `exec`/`files`, so
+inspect its declared extension and obtain connection details instead of sending
+an impossible shell command:
+
+```bash
+npx xapi-to sandbox quote \
+  --gpu-count 1 \
+  --gpu-model L4 \
+  --capabilities exec \
+  --max-hourly-usd 2.00
+
+npx xapi-to sandbox create \
+  --provider runpod \
+  --gpu-count 1 \
+  --max-hourly-usd 2.00 \
+  --wait
+
+npx xapi-to sandbox extension <id> runpod.connection_info \
+  --provider runpod \
+  --input '{}'
+
+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
+
+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.
+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
+
+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:
+
+```ts
+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');
+
+const sandbox = new XapiAgentsSandboxClient({
+  apiKey: sandboxApiKey,
+  sandboxHost: 'sandbox.test.xapi.to',
+  provider: 'daytona',
+  model: 'deepseek-v4-pro',
+});
+const modelProvider = new OpenAIProvider({
+  apiKey: aiApiKey,
+  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',
+  defaultManifest: new Manifest({ root: sandbox.workspaceRoot }),
+  capabilities: [shell()],
+  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 },
+  });
+  console.log(result.finalOutput);
+} finally {
+  await sandbox.lastSession?.close();
+}
+```
+
+Use `useResponses: false` because `ai.xapi.to` currently implements the OpenAI
+Chat Completions-compatible protocol. Disable tracing unless a separate OpenAI
+telemetry credential is configured; do not send an xAPI key to OpenAI tracing.
+Keep `XAPI_AI_KEY` and `XAPI_SANDBOX_KEY` separate for a mixed environment:
+the former is sent only to production `ai.xapi.to`, while the latter is sent
+only to `sandbox.test.xapi.to`. A production key with both permissions may be
+injected into both variables, but a Sandbox test key must not be assumed to
+have production AI Gateway access.
+The current adapter honestly supports an empty Manifest and Shell capability.
+It rejects Manifest file/mount/environment materialization until those mappings
+are implemented and tested.
+
+Run the real SDK + DeepSeek + Daytona acceptance test from the CLI repository:
+
+```bash
+XAPI_SANDBOX_KEY='<sandbox-test-key>' \
+XAPI_AI_KEY='<ai-production-key>' \
+npm run test:sandbox:openai -- \
+  --host sandbox.test.xapi.to \
+  --provider daytona \
+  --model deepseek-v4-pro
+```
+
+The script writes a redacted report, audits operations/events/usage/billing,
+terminates its instance, and fails if any active test instance remains.
+
+## Audit, history, and billing
+
+Inspect current state and service-calculated total:
+
+```bash
+npx xapi-to sandbox get <id> --format pretty
+```
+
+Read individual audit streams:
+
+```bash
+npx xapi-to sandbox audit <id> --kind operations
+npx xapi-to sandbox audit <id> --kind events
+npx xapi-to sandbox audit <id> --kind usageSegments
+npx xapi-to sandbox audit <id> --kind billingPeriods
+npx xapi-to sandbox history --state HISTORY --page-size 100
+```
+
+`history` is a separate paginated endpoint for prior instances; it is not an
+`audit --kind`. Filter it with `--search`, `--from`, and `--to` when reconciling
+a specific agent run.
+
+For acceptance, verify:
+
+1. create/exec/file/port/terminate operations have terminal success statuses;
+2. state events reach `TERMINATED`;
+3. no usage segment or billing period remains open;
+4. `totalCost` agrees with settled billing periods;
+5. `sandbox list` shows no active instance from the test.
+
+Use the returned billing data rather than recomputing cost from wall-clock time.
+
+## Run the real Playground acceptance suite
+
+From an xapi-cli development checkout, run the same nine real workflows 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
+ACTIVE (unrelated pre-existing account instances are still reported):
+
+```bash
+npm run test:sandbox:playground -- --host sandbox.test.xapi.to
+
+# Focus a rerun or avoid the higher-cost GPU reservation
+npm run test:sandbox:playground -- --host sandbox.test.xapi.to --only 8,9
+npm run test:sandbox:playground -- --host sandbox.test.xapi.to --skip-gpu
+```
+
+The JSON report path is printed at completion. A provider capacity or HTTP 402
+balance error is an external test precondition failure, not proof that the
+scenario works; retain the error and a previous successful provider-specific
+report separately. For Cloudflare, success requires an external HTTP 200 with
+the expected page marker, not merely a returned Quick Tunnel hostname.
+
+## Failure and interruption recovery
+
+`sandbox run` handles ordinary exceptions, remote non-zero exits, `SIGINT`, and
+`SIGTERM` by attempting termination before it exits. `SIGKILL`, machine loss, or
+a network partition cannot run local cleanup.
+
+After an uncertain interruption:
+
+```bash
+npx xapi-to sandbox list --format table
+npx xapi-to sandbox get <suspected-id>
+npx xapi-to sandbox terminate <suspected-id> --wait-timeout 5m
+```
+
+If terminate returns a state-change conflict, inspect state and retry after the
+in-flight transition finishes. Do not treat an accepted operation response as
+completion; wait for the instance's observed terminal state.
+
+## AI operating rules
+
+When exposing Sandbox to an AI agent:
+
+1. Inject the xAPI key in the tool execution layer; never place it in prompts,
+   files, environment dumps, remote commands, logs, or model-visible output.
+2. Start with `offerings`/`quote` when selection or budget is uncertain.
+3. Prefer `sandbox run` for one-shot work and granular primitives only when the
+   task needs persistent state across calls.
+4. Set capabilities and a price ceiling narrowly enough for the task.
+5. Use `--background` only when the selected Offering declares
+   `backgroundExec`; then verify the listening port independently.
+6. Treat instance IDs as cleanup obligations and keep them in structured state.
+7. Put termination in `finally`; on interruption, enumerate and reconcile any
+   uncertain instances.
+8. Report stdout, exit code, final state, cost, and cleanup outcome separately.
+9. Never claim success from page/API structure alone—execute the relevant path,
+   verify its artifact or public URL, then check audit and residual instances.