@miosa/sdk 1.2.3 → 1.2.5

package/README.md

@@ -38,7 +38,7 @@ 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.miosa.ai
+console.log(url); // https://3000-<slug>.sandbox.<tenant-domain>
 
 await sbx.destroy();
 ```
@@ -47,6 +47,7 @@ await sbx.destroy();
 
 | 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 |
@@ -61,6 +62,29 @@ await sbx.destroy();
 | `miosa.completions` | OpenAI-compatible chat completions with SSE streaming |
 | `miosa.embeddings` | OpenAI-compatible embedding vectors |
 
+## Agent device routing
+
+Use the device facade before launching an orchestration workflow. It keeps the
+product model explicit without hiding the lower-level APIs:
+
+```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,
+});
+
+// Use Computers when the agent needs a full browser/desktop:
+const desktop = await miosa.computers.create({ name: "browser-agent" });
+```
+
 ## Sandbox sub-resources
 
 Every `Sandbox` instance exposes composable sub-resources:
@@ -99,36 +123,6 @@ 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",
-});
-```
-
-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
@@ -166,17 +160,47 @@ const sandboxes = await miosa.sandboxes.list({
 });
 ```
 
-White-label domain layers are separate:
+## Docker Deploy
 
-```text
-sandbox preview:     https://<port>-<slug>.sandbox.<preview-domain>
-durable deployment:  https://<slug>.<deployment-domain>
-custom domain:       https://app.customer.com
+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,
+});
+
+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));
+}
 ```
 
-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.
+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.
 
 ## Error handling