@miosa/sdk 3.2.4 → 3.3.0

package/README.md

@@ -434,6 +434,127 @@ The SDK retries `429` and `5xx` automatically (3 retries, exponential backoff +
 Sandbox `exec` requests are never retried, because a replayed command would run twice; see [Cancelling sandbox commands](#cancelling-sandbox-commands).
 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
+
+Create a ticket, then use the versioned `miosa-terminal-v1` WebSocket protocol.
+There is no typed WebSocket client: the complete wire contract is documented below.
+The Docker container must already exist and be running inside the sandbox.
+`command` and `args` launch the executable directly; do not combine them with `shell`.
+
+The example imports [`ws`](https://www.npmjs.com/package/ws) directly, so install it as a direct dependency of your application.
+The SDK's optional dependency does not make that import available under every package manager's dependency isolation rules.
+
+```bash
+npm install ws
+npm install --save-dev @types/ws   # TypeScript only
+```
+
+```ts
+import WebSocket from "ws";
+import { Miosa } from "@miosa/sdk";
+
+const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });
+// An existing ready sandbox with the hackerai-agent container already running.
+const sandboxId = process.env.MIOSA_SANDBOX_ID;
+if (!sandboxId) throw new Error("MIOSA_SANDBOX_ID is required");
+const sbx = await miosa.sandboxes.get(sandboxId);
+
+const ticket = await sbx.terminal.create({
+  cols: 100,
+  rows: 30,
+  cwd: "/home/user",
+  command: "docker",
+  args: ["exec", "-it", "hackerai-agent", "bash"],
+});
+
+const terminal = new WebSocket(ticket.wsUrl, "miosa-terminal-v1", {
+  headers: { Authorization: `Bearer ${ticket.streamAuth}` },
+});
+
+terminal.on("open", () => {
+  terminal.send(JSON.stringify({ type: "resize", cols: 120, rows: 40 }));
+  terminal.send(Buffer.from("pwd\n"));       // stdin bytes
+  // terminal.send(Buffer.from([3]));        // Ctrl-C
+});
+
+let exitCode: number | undefined;
+terminal.on("message", (data: WebSocket.RawData, isBinary: boolean) => {
+  const bytes = Array.isArray(data)
+    ? Buffer.concat(data)
+    : Buffer.isBuffer(data) ? data : Buffer.from(data);
+  if (isBinary) {
+    process.stdout.write(bytes);             // PTY bytes, never re-decoded
+    return;
+  }
+  const event = JSON.parse(bytes.toString("utf8"));
+  if (event.type === "exit") exitCode = event.exit_code;
+});
+
+terminal.on("close", (code: number) => {
+  console.log(`closed ${code}, exit ${exitCode ?? "unknown"}`);
+});
+terminal.on("error", console.error);
+
+// terminal.close(1000);                     // Deletes the remote PTY and its process.
+```
+
+Write each server binary frame straight to the sink (`process.stdout.write(data)`).
+Calling `data.toString()` per frame decodes every frame independently, so a UTF-8 sequence split across two PTY frames becomes replacement characters.
+
+### Frames
+
+Binary messages carry stdin or PTY output without a framing prefix.
+A PTY combines stdout and stderr into the same output stream; they are not separate channels.
+Neither direction is line-normalized.
+The only client text frame with a meaning is resize, `{"type":"resize","cols":120,"rows":40}`; every other client text frame is UTF-8 stdin.
+Standard ping and pong frames are supported.
+
+### Authentication
+
+`Authorization: Bearer <credential>` accepts either the ticket's scoped `streamAuth` or your account API key.
+Browser clients that cannot set headers may pass the scoped token as `?token=<streamAuth>` on `wsUrl` instead.
+When both are supplied the header wins, so a stale query token cannot override a valid header.
+`ticket.streamAuthExpiresAt` and `ticket.expiresAt` are Unix epoch seconds, one hour after creation; after that the scoped token no longer authorizes a connection, while an API key still does.
+
+### Exit and close
+
+When the process exits, the server drains its remaining output, sends the text frame `{"type":"exit","exit_code":7}`, and then closes with `1000`.
+That text frame is the only source of the exit code: a close code never carries it.
+If the upstream stream fails without a confirmed process result, the server closes with `1011` and sends no exit frame, rather than inventing a successful exit code.
+
+| Close code | Meaning |
+|---|---|
+| `1000` | Normal close: process exited, sandbox disconnected, or the client closed |
+| `1011` | Upstream terminal failure with no confirmed process result |
+| `4001` | Authentication failed |
+| `4003` | Forbidden |
+| `4004` | Sandbox not found |
+| `4009` | Sandbox not running |
+| `4013` | Tenant stream limit reached |
+
+A client close with code `1000` (or with no status code) deletes the remote PTY and terminates its process.
+`await sbx.terminal.delete(ticket.sessionId)` does the same and is idempotent.
+
+### Reconnecting
+
+Any other close, and a dropped transport, leaves the session alive for the guest's 30-second reconnect grace window; a network error is never treated as permission to delete a live PTY.
+Reconnect by dialing the same `ticket.wsUrl` again, which already carries `session_id`, with a credential that is still valid.
+After an interrupted transport or a transient `1011` without a confirmed process exit, reconnect only once the previous socket is fully closed (a session accepts one active connection at a time), and within those 30 seconds.
+Reconnection is an attempt, not proof the process survived; after the grace window the PTY is gone and a new `terminal.create()` is required.
+Do not reconnect a session after receiving its process exit event.
+`4001`, `4003`, `4004`, `4009` and `4013` are terminal for that attempt: retrying them without fixing credentials, the sandbox state, or your concurrency simply fails again.
+
+### Direct command launch
+
+`command`/`args` are passed to process creation literally, with no implicit shell parsing.
+`terminal.create()` rejects locally decidable misuse with a `MiosaError` carrying `INVALID_TERMINAL_OPTIONS`: `shell` combined with `command`, `args` without `command`, more than 256 arguments, or a non-string/NUL-bearing argument.
+The server validates every option independently and answers `400 INVALID_TERMINAL_OPTIONS`, so client-side checks make failures earlier and cheaper, not authoritative.
+Command launch requires both a platform and guest release that supports it.
+Older control planes can ignore these options and return a ticket for the default shell, so a ticket alone does not prove the requested executable started.
+Confirm that the platform supports direct command launch and verify the process or container through its output before relying on that execution context.
+On a compatible platform, an older guest that cannot handle direct command launch rejects the request instead of silently substituting a default shell.
+For a managed `docker exec` terminal, `cwd` and `env` configure the container exec, and `/home/user` is the documented shared path across the file and command API boundary.
+
 ## Configuration
 
 | Option | Env var | Default |