@miosa/sdk 3.4.1 → 3.6.0

package/README.md

@@ -69,6 +69,14 @@ await sbx.pause();
 | `miosa.runtimeEnv` | Inherited tenant/workspace/project runtime environment variables |
 | `miosa.completions` | OpenAI-compatible chat completions with SSE streaming |
 | `miosa.embeddings` | OpenAI-compatible embedding vectors |
+| `miosa.environments` | Machine templates: repositories, variables, secret files, credential toggles, versions |
+| `miosa.snapshots` | Account-wide snapshot history, browse, download, fork, and `snapshots.named` |
+| `miosa.billTo` | Who pays for new machines: bill-to organization, limits, member caps |
+| `miosa.agentSettings` | Agents tab: provider credentials, harness settings, model catalog, sign-ins |
+| `miosa.connections` | One read-model for model providers, apps and tool servers |
+| `miosa.agentChats` | A chat's context use and compaction |
+| `miosa.aiGateway` | AI gateway policies, budget, limits and request traces |
+| `miosa.whoami()` | Who the presented credential is |
 
 ## Durable generated apps
 
@@ -390,6 +398,99 @@ console.log(rotated.viewer_password);
 await computer.destroy();
 ```
 
+## Computer use
+
+Drive a computer by action name. The names are the members of Anthropic's `computer_toolset_20260801`, and every result is typed.
+
+```ts
+const shot = await computer.act("screenshot");              // imageBase64, width, height
+const at = await computer.act("cursor_position");           // x, y
+await computer.act("left_click", { coordinate: [512, 384] });
+await computer.act("key", { text: "ctrl+s" });
+
+const view = await computer.look();                          // screenshot and accessibility tree in one call
+await computer.waitForDesktop();                             // ready and answering
+await computer.waitUntilIdle();                              // screen stopped changing
+const viewer = await computer.viewerUrl({ ttlSeconds: 3600 }); // { url, expiresAt, ... }
+```
+
+The rest of the desktop is on `computer.desktop`: `hotkey`, `keyDown`, `keyUp`, `mouseDown`, `mouseUp`, `getClipboard`, `setClipboard`, `screenSize`, `accessibilityTree`, `environment`, `setWallpaper`, `screenshotRegion` and window calls (`windowSize`, `resizeWindow`, `moveWindow`, `maximizeWindow`, `minimizeWindow`, `closeWindow`).
+
+`computer` and `sandbox` implement `Symbol.asyncDispose`, so `await using computer = await miosa.computers.create(...)` destroys it when the scope ends (TypeScript 5.2 or newer; Node 18.18 or newer).
+
+### Let Claude drive it
+
+```ts
+import { miosaComputerToolset } from "@miosa/sdk/computer-use";
+
+const toolset = miosaComputerToolset(computer, {
+  confirm: async ({ member, input }) => member !== "type" || askHuman(input), // required
+});
+// tools: [toolset] in anthropic.beta.messages.toolRunner(...), or toolset.toJSON() and toolset.toolResult(block) in your own loop.
+```
+
+`@miosa/sdk/computer-use` subclasses Anthropic's `BetaAbstractComputerToolset20260801`, so the batch rules (stop at the first failure, `Not executed: an earlier computer action in this turn failed.` for the rest, `toolset_name` on every result) come from Anthropic's runner.
+It needs the optional peer `@anthropic-ai/sdk` 0.133 or newer.
+`confirm` is required because the toolset can type and press keys; the alternative is to switch `type`, `key` and `hold_key` off in `configs`.
+`zoom` is a region screenshot.
+`triple_click` is off by default because the desktop has no triple-click route; `emulateTripleClick: true` sends a click and then a double-click.
+Screens are sent at their native size, so pick a 1024x768 or 1280x720 computer.
+For older models use `miosaComputerToolLegacy(computer, { version, displayWidthPx, displayHeightPx, confirm })`.
+
+See `examples/computer-use-claude.ts`.
+
+## End-user tokens (platform builders)
+
+`miosa.tokens.createScoped()` is the path for a platform that serves many customers.
+Your server mints a short-lived token for one end user and one workspace, and the browser holds only that token.
+It carries the scopes you ask for and never more than the minting key holds.
+
+```ts
+const { token, expires_at } = await miosa.tokens.createScoped({
+  userId: "end-user-123",
+  workspaceId: "ws_abc",
+  scopes: ["sandboxes:create", "sandboxes:read"],
+  expiresInSeconds: 3600,
+});
+// give `token` to the browser: new Miosa({ apiKey: token })
+```
+
+See `sdks/docs/guides/build-a-multi-tenant-platform.md` for the whole flow.
+
+## Helpers
+
+`@miosa/sdk/helpers` puts the calls an agent loop reaches for in one import, keyed by computer id.
+
+| Helper | Does |
+|---|---|
+| `waitUntilReady(miosa, id)` | poll until the computer is `active` or `running` |
+| `waitForDesktop(miosa, id)` | ready, and the desktop answers |
+| `waitUntilIdle(miosa, id)` | the screen stopped changing |
+| `waitForPrompt(miosa, runId)` | wait for an agent run to finish |
+| `streamPrompt(miosa, runId)` | follow an agent run's activity |
+| `streamEvents(miosa, id, { subscribe })` | follow window, file, process, clipboard and idle events |
+| `streamCommand(miosa, id, command)` | run a command and follow its output |
+| `execCommand(miosa, id, command)` | run a command and get the result |
+| `readText` / `writeText` | UTF-8 files |
+| `stopAndRemove(miosa, id)` | stop, then destroy; safe to call twice |
+
+Timeouts raise a `MiosaError` with a stable code (`COMPUTER_READY_TIMEOUT`, `DESKTOP_READY_TIMEOUT`, `DESKTOP_IDLE_TIMEOUT`) and `retryable: true`.
+
+## Fail fast
+
+Pass `failFast: true` to `sandboxes.create`, `fork`, `resume`, `computers.create` or `computer.start` to shed load instead of waiting for capacity.
+When no ready machine is free the server answers `503 no_ready_machine` in about 1.5 seconds, and the SDK raises `NoReadyMachineError`.
+A fail-fast request is never retried by the client, because the refusal is the point.
+
+```ts
+try {
+  const sbx = await miosa.sandboxes.create({ failFast: true, size: "large" });
+} catch (error) {
+  if (error instanceof NoReadyMachineError) return fallback(); // retryAfterMs is the server's hint
+  throw error;
+}
+```
+
 ## White-label / multi-tenant
 
 ```ts
@@ -415,6 +516,218 @@ Tenant preview-domain management is available through `miosa.tenant.previewDomai
 Tenant deployment-domain routing exists server-side; SDKs should consume
 deployment `public_url` instead of reconstructing it.
 
+## Environments
+
+An environment is the template a new sandbox or computer inherits when it starts.
+It carries repositories, variables, secret files, CLI tools, connections and four toggles that decide which of the owner's credentials the machine may use.
+Every save that changes what a machine receives creates exactly one immutable version.
+A machine pins the latest version when it starts and keeps it until you upgrade it.
+
+```ts
+const env = await miosa.environments.create({
+  name: "prod",
+  variables: { STRIPE_KEY: "sk_live_..." },
+  repositories: [{ repo: "octocat/hello-world", setupScript: "npm ci", setupBlocking: true }],
+  passSandboxCredentials: false,
+});
+
+// One atomic save: at most one new version, all or nothing.
+await miosa.environments.update("prod", {
+  variablesSet: { REGION: "us-east-1" },
+  variablesUnset: ["OLD_VAR"],
+  repositoriesUnset: ["octocat/old"],
+});
+
+const sbx = await miosa.sandboxes.create({ environment: "prod", env: { DEBUG: "1" } });
+console.log(sbx.data.environment_status, sbx.data.environment_version);
+
+// Machines move only when you say so. Secrets the new version withholds are deleted from the machine.
+await miosa.environments.upgrade("prod", { machineIds: [sbx.id] });
+```
+
+`environment`, `environmentId` and `noEnv` are accepted by `sandboxes.create`, `sandbox.resume`, `sandbox.fork`, `sandbox.snapshots.restore`, `computers.create`, `computer.start`, `snapshots.fork`, `snapshots.named.deploy` and `runs.run`.
+`noEnv: true` gives the same guarantee as a `safe_for_third_parties` environment: nothing of the owner's passes to that machine, permanently.
+`environments.effective(name)` shows the layers a machine would receive, with variable names but never values.
+Reveal calls (`revealVariable`, `revealFile`) are audit-logged.
+
+## Setup scripts and commands
+
+Pass `setupFile` when you create a sandbox or computer.
+It runs once, in the background, after the machine is ready, and never delays `ready`.
+
+```ts
+const sbx = await miosa.sandboxes.create({
+  setupFile: "#!/bin/bash\nnpm install || miosa-queue-prompt 'npm install failed'\n",
+  wait: 60, // hold the create request for up to 60 s; 201 either way, check sbx.ready
+});
+
+const status = await sbx.waitForSetup(); // done, failed, or null when there is no setup
+if (status.setup_status === "failed") console.error(status.setup_error, status.setup_repos);
+```
+
+`setupFile` is validated locally (UTF-8 text, at most 64 KiB, no NUL) before any machine exists, and a failed setup never destroys the machine.
+`wait` takes seconds (2 to 120) or `true`, and is the `?wait=` query on the create request.
+
+`sandbox.commands.execute()` and `computer.runCommand()` run a command synchronously (up to 600 seconds) with a relative `cwd`, `stdin` and the duration in the reply.
+
+```ts
+const result = await sbx.commands.execute("bash ./setup.sh", { cwd: "my-repo", timeoutSeconds: 120 });
+console.log(result.exit_code, result.duration_ms, result.timed_out);
+```
+
+A machine that is not ready answers a retryable `SandboxStartingError` or `ComputerStartingError`.
+The client already retries it using the server's `retry_after_ms`, so you only see it once the retry budget is spent.
+`sbx.agent.prompt(text)` and `sbx.agent.stop()` steer the agent run attached to the machine.
+
+## Snapshots
+
+`miosa.snapshots` is the account-wide view of snapshots for sandboxes and computers.
+Browsing and downloading read the snapshot's own disk image, so they work while the machine is stopped or destroyed.
+
+```ts
+const history = await miosa.snapshots.list({ resourceId: sbx.id });
+const tree = await miosa.snapshots.tree(history[0]!.id, "/home/user"); // waits through the 202 warm-up
+const bytes = await miosa.snapshots.download(history[0]!.id, "/home/user/notes.txt");
+const copy = await miosa.snapshots.fork(history[0]!.id, { environment: "prod" });
+
+// Named snapshots are pinned on purpose and never expire.
+await miosa.snapshots.named.create({ name: "web-stack", sandboxId: sbx.id });
+const { allowance } = await miosa.snapshots.named.list(); // 10 free names per organization
+await miosa.snapshots.named.deploy("web-stack");
+```
+
+Deleting is always explicit: `snapshots.delete(id)`, `snapshots.deleteMany(ids)` and `snapshots.deleteHistory(machineId)`.
+A snapshot with dependents answers `SnapshotInUseError`, which lists them in `.dependents`.
+Saving a name past the free allowance without credit answers `CreditRequiredError`.
+
+## Who pays: bill-to, limits and member caps
+
+A sandbox or computer bills the organization it is created in for its whole life.
+
+```ts
+await miosa.sandboxes.create({ billTo: "acme" }); // sent as X-Miosa-Bill-To
+await miosa.billTo.set("acme");                   // account-wide, for sessions and personal keys
+const limits = await miosa.billTo.limits();
+if (!limits.can_start) console.log(limits.blocked_reasons);
+await miosa.billTo.setMemberCaps(orgId, userId, { usageCapCents: 500, maxConcurrentSandboxes: 2 });
+```
+
+## Agents tab: credentials, harnesses, models, sign-ins
+
+```ts
+const settings = await miosa.agentSettings.get();
+await miosa.agentSettings.putCredential("openrouter", { fields: { api_key: "sk-or-..." }, usableBy: ["agents"] });
+await miosa.agentSettings.updateHarness("pi", { enabledProviders: ["anthropic", "openrouter"], defaultEffort: "medium" });
+const { models } = await miosa.agentSettings.models({ harness: "claude-code" });
+
+// Subscription sign-ins, including Kimi Code and Mistral Vibe.
+const session = await miosa.agentSettings.signins.start({ provider: "kimi_code" });
+console.log(session.user_code, session.verification_url);
+await miosa.agentSettings.signins.waitForCompletion(session.id);
+
+const { data } = await miosa.connections.list({ family: "models" });
+```
+
+Agents are bring-your-own-key.
+A harness with nothing connected answers `OwnCredentialsRequiredError` instead of falling back to a MIOSA key.
+
+## Chats, context and usage
+
+```ts
+const run = await miosa.runs.run({ runner: "claude-code", instruction: "...", chatId, targetKind: "sandbox", targetId });
+await miosa.runs.run({ runner: "claude-code", instruction: "and then?", chatId, targetKind: "sandbox", targetId }); // same session
+
+const ctx = await miosa.agentChats.context(chatId);
+if (ctx.compactable && (ctx.context?.used_ratio ?? 0) > 0.8) await miosa.agentChats.compact(chatId, { focus: "keep the plan" });
+
+const usage = await miosa.runs.usage({ groupBy: ["agent", "day"], from: "2026-10-01" });
+```
+
+## SSH and port tunnels
+
+```ts
+const info = await sbx.ssh.info();
+const cert = await sbx.ssh.createCertificate({ publicKey, ttlSeconds: 900 }); // nothing stays authorized afterwards
+
+// Needs the optional "ws" package. Binary frames, Bearer auth and the miosa-tunnel-v1 subprotocol are handled for you.
+const tunnel = await sbx.tunnel.open(3000);
+await tunnel.send(new TextEncoder().encode("GET / HTTP/1.0\r\n\r\n"));
+for await (const chunk of tunnel) process.stdout.write(chunk);
+
+// Node only, like `miosa proxy`.
+const forward = await sbx.tunnel.forward(3000, 8080);
+```
+
+### One call to a working `ssh` (Node)
+
+`ssh.connect()` makes an ed25519 key, gets a short-lived certificate for this sandbox, writes both with private modes (no `ssh-keygen` needed), starts a local relay and hands back the command.
+
+```ts
+import { spawn } from "node:child_process";
+
+const ssh = await sbx.ssh.connect({ ttlSeconds: 900 });
+console.log(ssh.commandLine); // ssh -i ... -o CertificateFile=... -p 54321 root@127.0.0.1
+console.log(ssh.config);      // a Host block for ~/.ssh/config
+const child = spawn(ssh.command[0]!, ssh.command.slice(1), { stdio: "inherit" });
+child.on("exit", () => void ssh.close()); // stops the relay and removes the temp dir
+```
+
+Pass `privateKeyPath` to use your own key, `dir` to keep the files, and `certificateRequest` for fields the platform adds to the certificate request.
+Call `ssh.renew()` before `ssh.validBefore` to get a fresh certificate for the same key.
+
+A tunnel that the server refuses closes with a code from the contract; the SDK raises `TunnelClosedError` with `.closeCode` and a stable `.code` such as `TUNNEL_SANDBOX_NOT_RUNNING`.
+
+## Identity, API key presets and the AI gateway
+
+```ts
+const me = await miosa.whoami();                 // user, organization, workspace, plan, scopes
+const presets = await miosa.apiKeys.presets();   // read-only, ci, agent, cli
+await miosa.apiKeys.create({ name: "ci", preset: "ci" }); // preset resolved to scopes for you
+
+// Every create option. `expiresAt` is sent as `expires_in_days` (the server takes a lifetime, not a date).
+const key = await miosa.apiKeys.create({
+  name: "partner-a",
+  scopes: ["sandboxes:read", "sandboxes:exec"],
+  expiresAt: new Date(Date.now() + 30 * 86_400_000),
+  allowedIps: ["203.0.113.0/24"],
+  rateLimitRpm: 600,
+  workspaceId: "ws_123",
+});
+await miosa.apiKeys.rotate(key.id, { name: "partner-a-2", overlapSeconds: 300 });
+
+await miosa.aiGateway.createPolicy({ name: "default", primaryModel: "gpt-6-astra", fallbackModels: ["claude-sonnet-5-5"] });
+const traces = await miosa.aiGateway.listRequests({ status: "error", limit: 50 });
+```
+
+OpenComputers `jobs.start()` runs a command and returns the job at once (202); follow it with `jobs.get()` and `jobs.stream()`.
+
+## Files
+
+Sandbox, managed-database and computer files go through the canonical filesystem API.
+
+```ts
+const sbx = await miosa.sandboxes.create();
+await sbx.files.write("/workspace/hello.txt", "hi");
+const { entries } = await sbx.files.list("/workspace");          // name, path, is_dir, size
+const tree = await sbx.files.tree("/workspace", 3);               // built from the listing
+const text = await sbx.files.readContent("/workspace/hello.txt"); // { content } or { content_base64 }
+const bytes = await sbx.files.download("/workspace/hello.txt");
+await sbx.files.mkdir("/workspace/out");
+await sbx.files.rename("/workspace/hello.txt", "/workspace/out/hello.txt");
+await sbx.files.uploadFile("/workspace/big.bin", blob);           // multipart, for large or binary files
+
+for await (const change of sbx.files.watch({ path: "/workspace", intervalMs: 5000 })) {
+  console.log(change.type, change.path);                         // created, modified, deleted
+}
+
+const dbFiles = miosa.databases.fs(databaseId);                   // same operations on /databases/:id/fs
+```
+
+`files.watch` polls the listing: the platform's SSE watch is served only on the sandbox host, not on `api.miosa.ai`.
+Each poll lists every directory down to `depth`, so keep `intervalMs` generous.
+`files.writeMany` is failure-atomic only when the response says `atomicity: "failure_atomic"`; never fall back to sequential writes.
+`/home/user` is the only path shared between the file API and a command run inside a Docker container.
+
 ## Error handling
 
 ```ts
@@ -432,6 +745,29 @@ try {
 
 The SDK retries `429` and `5xx` automatically (3 retries, exponential backoff + jitter). Set `maxRetries: 0` to disable.
 Sandbox `exec` requests are never retried, because a replayed command would run twice; see [Cancelling sandbox commands](#cancelling-sandbox-commands).
+Typed subclasses exist for the codes you are likely to branch on, and each keeps the base class the status always produced (`ValidationError`, `AuthError`, `NotFoundError`, `InsufficientCreditsError`, `RateLimitError`), so existing `instanceof` checks keep matching.
+
+| Class | Code | Retry |
+|---|---|---|
+| `InvalidIdError` | `INVALID_ID` (400) | no |
+| `OwnCredentialsRequiredError` | `OWN_CREDENTIALS_REQUIRED` (422) | no, connect a credential |
+| `EnvironmentNotFoundError` | `ENVIRONMENT_NOT_FOUND` (404 on an environment route) | no |
+| `UnknownEnvironmentError` | `ENVIRONMENT_NOT_FOUND` (422 on a machine route) | no |
+| `EnvironmentNameTakenError`, `EnvironmentIsDefaultError` | `ENVIRONMENT_NAME_TAKEN`, `ENVIRONMENT_IS_DEFAULT` (409) | no |
+| `EnvironmentScrubFailedError` | `ENVIRONMENT_SCRUB_FAILED` (409) | yes, nothing was saved |
+| `EnvironmentMemoryWithheldError` | `ENVIRONMENT_MEMORY_WITHHELD` (409, `.reasons`) | no |
+| `MachineKeyScopeError` | `MACHINE_KEY_SCOPE` (403) | no |
+| `SandboxStartingError`, `ComputerStartingError` | `SANDBOX_STARTING`, `COMPUTER_STARTING` (409) | yes, automatically, using `retry_after_ms` |
+| `CreditRequiredError` | `CREDIT_REQUIRED` (402) | no, add credit |
+| `TeamMemberCapReachedError`, `MemberLimitReachedError` | `TEAM_MEMBER_CAP_REACHED` (402), `MEMBER_LIMIT_REACHED` (429) | no |
+| `BillToLockedError`, `BillToForbiddenError`, `BillToSuspendedError` | `BILL_TO_*` (403) | no |
+| `OrgNotFoundError`, `AmbiguousOrgError` | `ORG_NOT_FOUND` (404), `AMBIGUOUS_ORG` (409) | no |
+| `SnapshotInUseError` | `SNAPSHOT_IN_USE` (409, `.dependents`) | no |
+| `RunSessionNotResumableError` | `RUN_SESSION_NOT_RESUMABLE` (409, `.reason`) | no |
+| `ChatBusyError` | `CHAT_BUSY` (409) | yes, once the latest run finishes |
+| `NoAgentRunError` | `NO_AGENT_RUN` (409) | no |
+| `InvalidSetupFileError` | `INVALID_SETUP_FILE` (422, `.reason`) | no |
+
 Every `MiosaError` carries `retryable` (server-supplied when present, otherwise `true` for 408/429/5xx and transport failures) and `requestId` for support correlation.
 
 ## Interactive sandbox terminals