@miosa/sdk 1.2.5 → 1.2.7

package/README.md

@@ -29,8 +29,11 @@ import { Miosa } from "@miosa/sdk";
 
 const miosa = new Miosa({ apiKey: "msk_live_..." });
 
-// Boot a sandbox, write a file, run a command
-const sbx = await miosa.sandboxes.create({ name: "my-build" });
+// Create or resume a persistent sandbox workspace, then work inside it.
+const sbx = await miosa.sandboxes.createAgentWorkspace({
+  name: "my-build",
+  externalWorkspaceId: "customer-workspace-123",
+});
 
 await sbx.files.write("/workspace/hello.ts", `console.log("hello from miosa")`);
 const result = await sbx.exec("npx tsx /workspace/hello.ts");
@@ -38,16 +41,17 @@ console.log(result.stdout); // hello from miosa
 
 // Expose a live preview URL
 const url = await sbx.expose(3000);
-console.log(url); // https://3000-<slug>.sandbox.<tenant-domain>
+console.log(url); // https://3000-<slug>.sandbox.miosa.ai
 
-await sbx.destroy();
+// Keep progress. Pause preserves the workspace so the next session can resume.
+await sbx.snapshots.create("after-hello-world");
+await sbx.pause();
 ```
 
 ## What's included
 
 | Resource | Description |
 |---|---|
-| `miosa.devices` | Agent device facade for routing work across sandboxes, computers, local devices, and Docker Deploy hosts |
 | `miosa.sandboxes` | Lightweight code-execution VMs — exec, files, snapshots, previews |
 | `miosa.computers` | Full Linux desktop VMs for computer-use agents |
 | `miosa.deployments` | Versioned production releases with rollback |
@@ -62,29 +66,53 @@ await sbx.destroy();
 | `miosa.completions` | OpenAI-compatible chat completions with SSE streaming |
 | `miosa.embeddings` | OpenAI-compatible embedding vectors |
 
-## Agent device routing
+## Agent workspaces
 
-Use the device facade before launching an orchestration workflow. It keeps the
-product model explicit without hiding the lower-level APIs:
+For AI builders, code assistants, and white-label agent products, the sandbox
+is the development machine. Do not run builds on the user's laptop and upload
+the result as the primary flow. Create or resume a stable sandbox workspace,
+write files under `/workspace`, run package installs/tests/builds inside the
+sandbox, expose previews from the sandbox, and publish from that sandbox.
 
 ```ts
-const catalog = miosa.devices.catalog();
-const inventory = await miosa.devices.list();
-
-// Default for code/build/test/preview work:
-const sbx = await miosa.sandboxes.create({
-  templateId: "nextjs",
-  timeoutSec: 3600,
-});
-await sbx.exec.run("codex 'build and test the requested app'", {
-  cwd: "/workspace",
-  timeout: 1800,
+const sbx = await miosa.sandboxes.getOrCreate({
+  name: "acme-marketing-page",
+  templateId: "miosa-sandbox",
+  persistent: true,
+  timeoutSec: 86_400,
+  idleTimeoutSec: 1800,
+  snapshotExpirationDays: 30,
+  keepLastSnapshots: 1,
+  externalWorkspaceId: "acme",
+  externalUserId: "jane",
+  waitUntilReady: true,
 });
 
-// Use Computers when the agent needs a full browser/desktop:
-const desktop = await miosa.computers.create({ name: "browser-agent" });
+await sbx.files.writeMany([
+  { path: "/workspace/package.json", content: `{"scripts":{"dev":"vite --host 0.0.0.0"}}` },
+  { path: "/workspace/index.html", content: `<main id="app"></main>` },
+]);
+
+for await (const event of sbx.exec.stream("cd /workspace && npm install && npm run dev -- --port 3000")) {
+  console.log(event);
+}
+
+const preview = await sbx.previews.create(3000);
+console.log(preview.url);
 ```
 
+`createAgentWorkspace()` is a convenience wrapper around `getOrCreate()` with
+builder defaults: a 24-hour activity cap, thirty-minute idle snapshot/pause,
+readiness waiting, 30-day snapshot-retention metadata, keep-last-snapshot
+metadata, and metadata that marks the sandbox as an agent workspace.
+
+That mirrors the Vercel-style persistent-sandbox model without keeping CPU
+running forever: activity extends the running session, idle workspaces are
+checkpointed and paused, and later sessions resume from the checkpoint. Use
+`extend(86_400)` before long builds, `pause()` when the user is done for now,
+`resume()` for the next session, `snapshots.create()` for manual checkpoints,
+and `destroy()` only when the workspace should be permanently deleted.
+
 ## Sandbox sub-resources
 
 Every `Sandbox` instance exposes composable sub-resources:
@@ -123,6 +151,56 @@ await sbx.pause();
 await sbx.resume();
 ```
 
+## Publish from sandbox
+
+Preview is mutable; publish creates a durable deployment version. Static output
+is served by MIOSA's artifact plane. Dynamic apps run in reconciled runtime VMs.
+
+```ts
+const deployment = await sbx.deploy({
+  name: "clinic-intake",
+  outputPath: "/workspace/dist",
+  entrypoint: "index.html",
+});
+
+console.log(deployment.url ?? deployment.deployment?.public_url);
+```
+
+For dynamic/full-stack apps:
+
+```ts
+const deployment = await sbx.deploy({
+  name: "clinic-intake-api",
+  outputPath: "/workspace",
+  runCommand: "npm start",
+  port: 3000,
+  domain: "intake.apps.cliniciq.com",
+});
+```
+
+For workspace Docker Deploy, publish from the same sandbox but choose the
+Docker Deploy target:
+
+```ts
+const deployment = await sbx.deployDocker({
+  name: "lead-magnet",
+  path: "/workspace",
+  buildCommand: "npm run build",
+  runCommand: "npm start",
+  port: 3000,
+});
+
+console.log(deployment.url ?? deployment.public_url);
+```
+
+Docker Deploy runs app containers inside the workspace's dedicated MIOSA
+Docker Deploy appliance VM. It is separate from normal MIOSA dynamic runtime
+VMs and is useful when a workspace needs many small apps, funnels, lead
+magnets, APIs, or client sites.
+
+Always display the server-returned `url` / `public_url`. Do not hardcode
+`preview.miosa.app`, `api.miosa.app`, or `<tenant>.miosa.app`.
+
 ## Desktop control (Computers)
 
 ```ts
@@ -160,47 +238,17 @@ const sandboxes = await miosa.sandboxes.list({
 });
 ```
 
-## Docker Deploy
-
-Use Docker Deploy when a sandbox-built app should run as a container on the
-workspace Docker appliance.
-
-```ts
-const templates = await miosa.deployments.listDockerDeployTemplates({
-  framework: "nextjs",
-  includePreview: true,
-});
-const template = templates[0];
-
-await miosa.deployments.ensureDockerDeployHost({
-  workspaceId: "workspace-uuid",
-  size: "small",
-});
-
-const sbx = await miosa.sandboxes.create({ templateId: "nextjs" });
-// Build or sync the app into /workspace...
-
-const published = await sbx.deployDocker({
-  name: "customer-site",
-  outputPath: "/workspace",
-  port: 3000,
-  dockerDeployTemplateId: template.id,
-});
+White-label domain layers are separate:
 
-const deploymentId = String(published.deployment_id ?? published.id);
-const proof = await miosa.deployments.doctorDockerDeploy(deploymentId, {
-  probePath: "/",
-});
-
-if (!proof.ok) {
-  throw new Error(JSON.stringify(proof.checks, null, 2));
-}
+```text
+sandbox preview:     https://<port>-<slug>.sandbox.<preview-domain>
+durable deployment:  https://<slug>.<deployment-domain>
+custom domain:       https://app.customer.com
 ```
 
-Template responses include app files plus optional `design_md`,
-`design_source_url`, `design_sources`, and `design_reference_presets` so agents
-can generate the app with the same design context they later attach to the
-Docker Deploy publish.
+Tenant preview-domain management is available through `miosa.tenant.previewDomain`.
+Tenant deployment-domain routing exists server-side; SDKs should consume
+deployment `public_url` instead of reconstructing it.
 
 ## Error handling