xapi-to 0.1.20 → 0.1.21

package/dist/openai-sandbox-client.js

@@ -7,7 +7,7 @@ import {
   sandboxQuote,
   sandboxStateAction,
   sandboxWait
-} from "./chunk-TYY6JR6O.js";
+} from "./chunk-UEQCIJ7T.js";
 
 // src/openai-sandbox-client.ts
 import { randomUUID } from "crypto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xapi-to",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Agent-friendly CLI for xapi - discover and call capabilities and APIs",
   "type": "module",
   "bin": {

package/skills/xapi/SKILL.md

@@ -466,8 +466,6 @@ The full catalog also spans many other categories — crypto/on-chain data, CEX
 
 The CLI retries idempotent metadata reads and `task poll` for transient timeouts, network failures, `408`, `429`, and `502`–`504`. It does not automatically retry arbitrary `call` actions because the upstream may already have completed a write; confirm the result before manually retrying posts, payments, or other mutations. Ordinary JSON execution has a 60-second request ceiling. HTTP SSE streams and raw downloads instead use a 60-second no-data timeout, reset whenever a chunk arrives; override it with `XAPI_TRANSFER_IDLE_TIMEOUT_MS` when an upstream legitimately pauses longer.
 
-## Tips
-
 - Use `--page` and `--page-size` for pagination on `list`, `search`, and `services`.
 
 ## Specialized Guides
@@ -489,6 +487,7 @@ When the user's task involves these workflows, read the corresponding guide file
 - **`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)
+- **`guides/provider.md`** — Provider management: create/update services, About/changelog, version lifecycle, metrics/events and request receipts, Skill upload/linking, rollback/delete, earnings transfer
 
 ## Security
 

package/skills/xapi/guides/provider.md

@@ -0,0 +1,198 @@
+# 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.
+
+## 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/src/client.ts

@@ -26,6 +26,13 @@ export interface ClientOptions {
   apiKey?: string;
 }
 
+export interface ApiKeyApiRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  body?: unknown;
+  timeoutMs?: number;
+  retries?: number;
+}
+
 export class HttpError extends Error {
   constructor(
     public readonly status: number,
@@ -100,8 +107,28 @@ function parseRetryAfterMs(res: Response): number | undefined {
   return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function abortError(signal?: AbortSignal | null): Error {
+  const reason = signal?.reason;
+  return reason instanceof Error
+    ? reason
+    : new DOMException('The operation was aborted', 'AbortError');
+}
+
+function sleep(ms: number, signal?: AbortSignal | null): Promise<void> {
+  if (signal?.aborted) return Promise.reject(abortError(signal));
+  return new Promise((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onAbort = () => {
+      if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      reject(abortError(signal));
+    };
+    timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
 }
 
 export async function request<T>(
@@ -138,7 +165,7 @@ export async function request<T>(
         if (isRetryableStatus(res.status) && attempt < retries) {
           await res.text().catch(() => ''); // drain body so the socket can be reused
           clearTimeout(timer);
-          await sleep(backoffDelayMs(attempt, retryAfterMs));
+          await sleep(backoffDelayMs(attempt, retryAfterMs), callerSignal);
           attempt++;
           continue;
         }
@@ -174,7 +201,7 @@ export async function request<T>(
       if (timedOut) {
         const timeoutError = new RequestTimeoutError(timeoutMs);
         if (attempt < retries) {
-          await sleep(backoffDelayMs(attempt));
+          await sleep(backoffDelayMs(attempt), callerSignal);
           attempt++;
           continue;
         }
@@ -182,7 +209,7 @@ export async function request<T>(
       }
       if (isRetryableNetworkError(e) && attempt < retries) {
         clearTimeout(timer);
-        await sleep(backoffDelayMs(attempt));
+        await sleep(backoffDelayMs(attempt), callerSignal);
         attempt++;
         continue;
       }
@@ -200,6 +227,30 @@ function headers(apiKey?: string): Record<string, string> {
   return h;
 }
 
+/** Call a scoped API-Key control-plane endpoint without exchanging for a JWT. */
+export function apiKeyApiRequest<T>(
+  apiHost: string,
+  apiKey: string,
+  path: string,
+  options: ApiKeyApiRequestOptions = {},
+): Promise<T> {
+  const method = options.method ?? 'GET';
+  const requestHeaders: Record<string, string> = { 'XAPI-KEY': apiKey };
+  if (options.body !== undefined) requestHeaders['Content-Type'] = 'application/json';
+  return request<T>(
+    `${scheme(apiHost)}://${apiHost}${path}`,
+    {
+      method,
+      headers: requestHeaders,
+      ...(options.body !== undefined
+        ? { body: JSON.stringify(options.body) }
+        : {}),
+    },
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    options.retries ?? 0,
+  );
+}
+
 function baseUrl(opts: ClientOptions): string {
   return `${scheme(opts.actionHost)}://${opts.actionHost}`;
 }

package/src/sandbox-client.ts

@@ -26,6 +26,7 @@ export interface SandboxRequirements {
   gpu?: { count?: number; model?: string };
   regions?: string[];
   capabilities?: string[];
+  minContinuousRuntimeSeconds?: number;
   [key: string]: unknown;
 }
 
@@ -263,24 +264,43 @@ export async function sandboxWait(
   signal?: AbortSignal,
 ): Promise<SandboxDetail> {
   const deadline = Date.now() + timeoutMs;
+  const deadlineController = new AbortController();
+  const abortFromCaller = () => deadlineController.abort();
+  const deadlineTimer = setTimeout(() => deadlineController.abort(), Math.max(0, timeoutMs));
+  if (signal?.aborted) deadlineController.abort();
+  else signal?.addEventListener('abort', abortFromCaller, { once: true });
   let last: SandboxDetail | undefined;
-  while (Date.now() < deadline) {
-    if (signal?.aborted) throw new Error(`sandbox wait interrupted while waiting for ${wanted.join(' or ')}`);
-    last = await sandboxGet(opts, id, signal);
-    const state = String(last.observedState || '');
-    if (wanted.includes(state)) return last;
-    if (['FAILED', 'TERMINATED'].includes(state) && !wanted.includes(state)) {
-      throw new Error(`sandbox ${id} entered ${state} while waiting for ${wanted.join(' or ')}`);
+  try {
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw new Error(`sandbox wait interrupted while waiting for ${wanted.join(' or ')}`);
+      try {
+        last = await sandboxGet(opts, id, deadlineController.signal);
+      } catch (error) {
+        if (signal?.aborted) {
+          throw new Error(`sandbox wait interrupted while waiting for ${wanted.join(' or ')}`);
+        }
+        if (Date.now() >= deadline) break;
+        throw error;
+      }
+      if (Date.now() >= deadline) break;
+      const state = String(last.observedState || '');
+      if (wanted.includes(state)) return last;
+      if (['FAILED', 'TERMINATED'].includes(state) && !wanted.includes(state)) {
+        throw new Error(`sandbox ${id} entered ${state} while waiting for ${wanted.join(' or ')}`);
+      }
+      await new Promise<void>((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          signal?.removeEventListener('abort', done);
+          resolve();
+        };
+        const timer = setTimeout(done, Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+        signal?.addEventListener('abort', done, { once: true });
+      });
     }
-    await new Promise<void>((resolve) => {
-      const done = () => {
-        clearTimeout(timer);
-        signal?.removeEventListener('abort', done);
-        resolve();
-      };
-      const timer = setTimeout(done, Math.min(intervalMs, Math.max(0, deadline - Date.now())));
-      signal?.addEventListener('abort', done, { once: true });
-    });
+  } finally {
+    clearTimeout(deadlineTimer);
+    signal?.removeEventListener('abort', abortFromCaller);
   }
   throw new Error(
     `sandbox ${id} did not enter ${wanted.join(' or ')} within ${timeoutMs}ms` +