@miosa/sdk 1.2.15 → 1.2.17

package/README.md

@@ -63,9 +63,46 @@ await sbx.pause();
 | `miosa.settings` | Workspace config, branding, BYOK provider keys |
 | `miosa.webhooks` | Outgoing tenant webhooks — CRUD, test, delivery history |
 | `miosa.openComputers` | BYOC host management — register your own machines |
+| `miosa.devices` | Unified device facade for sandbox/computer list, exec, files, previews |
+| `miosa.connectors` | Provider credentials and short-lived runtime tokens |
+| `miosa.runtimeEnv` | Inherited tenant/workspace/project runtime environment variables |
 | `miosa.completions` | OpenAI-compatible chat completions with SSE streaming |
 | `miosa.embeddings` | OpenAI-compatible embedding vectors |
 
+## Connect vs Egress
+
+Use **Connect** when your product needs to manage provider credentials for
+agents, sandboxes, computers, or deployments. Connect owns the product-level
+contract: connectors, installations, project links, inherited defaults,
+short-lived tokens, white-label attribution, and runtime bindings.
+
+Use **Egress** when you need the low-level security boundary: encrypted secret
+storage, outbound host allowlists, placeholder token exchange, and audit logs.
+Egress is the enforcement layer under Connect. Most white-label apps should
+call `miosa.connectors` and runtime binding helpers first; only call
+`miosa.secrets`, `miosa.network`, or `miosa.audit` when you are building
+security/admin controls directly.
+
+```ts
+// Product-level credential setup.
+const connector = await miosa.connectors.create("anthropic", {
+  name: "workspace-claude",
+  scope: "workspace",
+  externalWorkspaceId: "clinic-iq",
+  value: process.env.ANTHROPIC_API_KEY,
+});
+
+// Runtime-level materialization: the sandbox sees ANTHROPIC_API_KEY, but your
+// app does not get the raw provider key back from MIOSA.
+await miosa.connectors.materializeDefaults({
+  workspaceId: "workspace-id",
+  resourceType: "sandbox",
+  resourceId: sbx.id,
+  target: "agent",
+  externalWorkspaceId: "clinic-iq",
+});
+```
+
 ## Agent workspaces
 
 For AI builders, code assistants, and white-label agent products, the sandbox
@@ -101,6 +138,26 @@ const preview = await sbx.previews.create(3000);
 console.log(preview.url);
 ```
 
+For platform agents that plan work outside the sandbox and then hand execution
+to a runtime inside the sandbox/computer, use the unified device API:
+
+```ts
+await miosa.devices.writeFile(sbx.id, {
+  path: "/workspace/PLAN.md",
+  content: "# Build plan\nUse the customer profile and export /workspace/out.",
+});
+
+const build = await miosa.devices.exec(sbx.id, {
+  command: "npm install && npm run build",
+  cwd: "/workspace",
+  timeoutMs: 600_000,
+});
+
+const artifact = await miosa.devices.readFile(sbx.id, {
+  path: "/workspace/out/report.pdf",
+});
+```
+
 `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