@tangle-network/sandbox 0.10.4 → 0.10.5-develop.20260715115519.fee3d86

package/README.md

@@ -206,9 +206,54 @@ client.connect();
 detection, replay-on-reconnect, and `lastEventId` persistence. None of this requires a
 Durable Object.
 
+Server-originated product events can arrive before the browser connects:
+
+```typescript
+await client.broadcastSessionAgentEvent(sessionId, {
+  type: "project.provision_progress",
+  properties: { message: "Creating workspace" },
+});
+```
+
+The public API binds that pending queue to the authenticated product and Sandbox account and commits it to Redis before returning `success: true`.
+A later connection by the same owner leases and acknowledges the ordered queue; another owner receives none of it.
+A gateway crash before acknowledgement redelivers the same event IDs, which the default `SessionGatewayClient` deduplicates before invoking handlers.
+
 See `examples/cf-worker-chat.ts`, `examples/browser-streaming-resume.ts`, and
 `examples/reconnect-from-last-event-id.ts` for end-to-end patterns.
 
+### Browser-safe scoped runtime client
+
+`@tangle-network/sandbox/runtime` is a browser- and Worker-safe entry point
+(no `node:` imports) for talking directly to one sandbox's runtime with a
+short-lived scoped token — never the account-level Sandbox API key — minted
+server-side via `box.mintScopedToken({ scope: "session-runtime", sessionId })`
+or `box.mintScopedToken({ scope: "read-only" })`.
+
+```typescript
+import { createSandboxRuntimeClient } from "@tangle-network/sandbox/runtime";
+
+const runtime = createSandboxRuntimeClient({
+  baseUrl: scopedToken.sidecarProxyUrl, // browser-safe proxy base from box.mintScopedToken()
+  token: scopedToken.token,
+});
+
+await runtime.writeFile("/workspace/notes.md", "# from the browser");
+
+// Binary-safe, chunked upload for payloads over ~1 MiB — same engine and
+// size contract as SandboxInstance.fs.uploadData, wired to the scoped token
+const blob = await fileInput.files[0].arrayBuffer();
+await runtime.uploadData("/workspace/uploads/file.bin", blob, {
+  onProgress: (p) => console.log(`${p.percentage.toFixed(1)}%`),
+});
+```
+
+Every method on the scoped client — `writeFile`, `readFiles`, `uploadData`,
+terminals, sessions — carries the same `Authorization: Bearer <token>` header
+and base URL prefix, so the request conventions match whether the token
+scope allows the call or not; a denied call fails with the typed
+`SandboxError`, not a silent no-op.
+
 ## Features
 
 - **Sandbox Management** - Create, list, stop, resume, and delete sandboxes
@@ -714,6 +759,70 @@ for await (const event of box.events({ signal: controller.signal })) {
 }
 ```
 
+### File I/O
+
+| Method | Environment | Payload | Notes |
+|---|---|---|---|
+| `fs.read(path)` / `fs.write(path, content, options?)` | Node + browser | UTF-8 string, or base64 via `options.encoding` | Single request — see the size contract below for the cap |
+| `fs.writeMany(files, options?)` | Node + browser | Same as `write`; per-file `encoding` | Paced, retry-aware batch through `fs.write`'s endpoint; fails loud on the first file that can't be written |
+| `fs.upload(localPath, remotePath, options?)` | Node only | Local file path | Reads the local file with `node:fs`; not available in a browser tab |
+| `fs.uploadData(remotePath, data, options?)` | Node + browser | `Blob \| ArrayBuffer \| ArrayBufferView \| string` | Browser/Worker-safe, binary-safe — the sanctioned path for payloads over ~1 MiB (see below) |
+| `fs.download(remotePath, localPath, options?)` | Node only | — | Writes to a local path with `node:fs` |
+| `fs.uploadDir` / `fs.downloadDir` | Node only | Local directory path | tar-based directory transfer |
+| `fs.list` / `fs.stat` / `fs.mkdir` / `fs.delete` / `fs.rename` / `fs.exists` | Node + browser | — | Directory listing and file metadata operations |
+
+```typescript
+// Text write/read (UTF-8 by default)
+await box.fs.write("/workspace/config.json", JSON.stringify(config));
+const raw = await box.fs.read("/workspace/config.json");
+
+// Base64 for binary content through the same single-shot endpoint
+await box.fs.write("/workspace/icon.png", base64Png, { encoding: "base64" });
+
+// Batch-write many small files (paced, retried)
+await box.fs.writeMany([
+  { path: "skills/review.md", content: reviewSkill },
+  { path: "assets/logo.png", content: base64Logo, encoding: "base64" },
+]);
+
+// Node-only: upload a local file
+await box.fs.upload("./model.bin", "/workspace/models/model.bin");
+
+// Browser/Worker-safe: upload in-memory data over ~1 MiB (e.g. an
+// <input type="file"> Blob) — chunked and verified end-to-end
+const blob = await fetch("https://example.com/model.bin").then((r) => r.blob());
+await box.fs.uploadData("/workspace/models/model.bin", blob, {
+  onProgress: (p) => console.log(`${p.percentage.toFixed(1)}%`),
+});
+
+await box.fs.download("/workspace/results.zip", "./results.zip");
+```
+
+`fs.uploadData` is the sanctioned path once a payload clears the single-shot
+write cap: it splits the payload into server-sized parts against a chunked
+upload-session and verifies the whole payload with a SHA-256 at commit, so
+it's safe for arbitrarily-shaped binary content (video, model weights,
+archives) up to the session cap. It works identically whether the sandbox is
+reached through the gateway proxy or a direct sidecar connection
+(`box.direct()`).
+
+#### File size contract
+
+| Surface | Cap | Constant | Failure |
+|---|---|---|---|
+| Single-shot decoded write (`fs.write`, `fs.writeMany`) | 5 MiB | `FILE_DECODED_WRITE_MAX_BYTES` | `FILE_TOO_LARGE` |
+| Gateway proxy request (wire, any route) | 1 MiB | `SANDBOX_PROXY_REQUEST_MAX_BYTES` | `PAYLOAD_TOO_LARGE` |
+| Direct-runtime write request (wire, `box.direct()` only) | 32 MiB | `SANDBOX_DIRECT_FILE_REQUEST_MAX_BYTES` | `PAYLOAD_TOO_LARGE` |
+| Multipart upload (`fs.upload`) | 5 MiB | `FILE_MULTIPART_UPLOAD_MAX_BYTES` | `FILE_TOO_LARGE` |
+| Chunked upload part (`fs.uploadData`, internal) | 768 KiB | `FILE_UPLOAD_PART_MAX_BYTES` | — (server-sized, transparent to callers) |
+| Chunked upload session (`fs.uploadData`) | 64 MiB | `FILE_UPLOAD_SESSION_MAX_BYTES` | `PAYLOAD_TOO_LARGE` |
+
+All constants are exported from `@tangle-network/runtime-contracts`. Use
+`fs.uploadData` for anything above the single-shot caps. `PAYLOAD_TOO_LARGE`
+means split the delivery (use `fs.uploadData` instead of one request);
+`FILE_TOO_LARGE` means the content itself exceeds what that surface accepts,
+no matter how it's delivered.
+
 ### Snapshots
 
 #### `box.snapshot(options?)`

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
-import { D as CodeLanguage, E as CodeExecutionResult, T as CodeExecutionOptions, k as CodeResultPart } from "../types-BvSoEHz8.js";
-import { n as SandboxInstance } from "../sandbox-BtNWbfd3.js";
-import { i as SandboxClient } from "../client-B8i6qrQr.js";
+import { D as CodeExecutionOptions, O as CodeExecutionResult, j as CodeResultPart, k as CodeLanguage } from "../types-LNLeU9Ub.js";
+import { n as SandboxInstance } from "../sandbox-B9P4tyt4.js";
+import { i as SandboxClient } from "../client-CSaBJ8wD.js";
 import * as _$_modelcontextprotocol_sdk_server_index_js0 from "@modelcontextprotocol/sdk/server/index.js";
 
 //#region src/agent/tools/_specs.d.ts

package/dist/{client-B8i6qrQr.d.ts → client-CSaBJ8wD.d.ts}

@@ -1,5 +1,5 @@
-import { Bn as SandboxClientConfig, Bt as IntelligenceReport, Cn as PublishPublicTemplateVersionOptions, Di as UsageInfo, Dn as ReconcileSandboxFleetsResult, En as ReconcileSandboxFleetsOptions, F as CreateSandboxFleetOptions, Gn as SandboxFleetArtifactSpec, Hn as SandboxEnvironment, Ht as IntelligenceReportCompareTo, I as CreateSandboxFleetTokenOptions, Jn as SandboxFleetDispatchResponse, Jt as ListSandboxFleetOptions, Kn as SandboxFleetCostEstimate, L as CreateSandboxFleetWithCoordinatorOptions, N as CreateIntelligenceReportOptions, P as CreateRequestOptions, R as CreateSandboxOptions, Sn as PublishPublicTemplateOptions, Sr as SandboxProfileSummary, Tn as ReapExpiredSandboxFleetsResult, Ur as SecretsManager, Vt as IntelligenceReportBudget, Wn as SandboxFleetArtifact, Wt as IntelligenceReportWindow, Yn as SandboxFleetDriverCapability, Yt as ListSandboxOptions, Zn as SandboxFleetInfo, _ as BatchResult, _r as SandboxInfo, _t as FleetExecDispatchResult, a as AttachSandboxFleetMachineOptions, ar as SandboxFleetOperationsSummary, bn as PublicTemplateInfo, bt as FleetPromptDispatchResult, ci as SubscriptionInfo, cr as SandboxFleetTraceBundle, dr as SandboxFleetTraceOptions, et as ExecOptions, fr as SandboxFleetUsage, ft as FleetDispatchCancelResult, g as BatchOptions, gr as SandboxFleetWorkspaceSnapshotResult, gt as FleetExecDispatchOptions, hn as PromptResult, hr as SandboxFleetWorkspaceRestoreResult, ht as FleetDispatchStreamOptions, ii as SshKeysManager, m as BatchEvent, mn as PromptOptions, mr as SandboxFleetWorkspaceReconcileResult, mt as FleetDispatchResultBufferOptions, pn as PromptInputPart, pt as FleetDispatchResultBuffer, rr as SandboxFleetManifest, sr as SandboxFleetToken, tr as SandboxFleetMachineRecord, tt as ExecResult, v as BatchRunOptions, vt as FleetMachineId, wn as ReapExpiredSandboxFleetsOptions, x as BatchTask, xi as TokenRefreshHandler, xn as PublicTemplateVersionInfo, y as BatchRunRequest, yt as FleetPromptDispatchOptions } from "./types-BvSoEHz8.js";
-import { a as TraceExportSink, i as TraceExportResult, n as SandboxInstance, t as HttpClient } from "./sandbox-BtNWbfd3.js";
+import { $n as SandboxFleetDriverCapability, An as ReconcileSandboxFleetsResult, B as CreateSandboxOptions, Cn as PublicTemplateInfo, Ct as FleetPromptDispatchResult, Dn as ReapExpiredSandboxFleetsOptions, En as PublishPublicTemplateVersionOptions, Er as SandboxProfileSummary, F as CreateIntelligenceReportOptions, Gt as IntelligenceReportCompareTo, I as CreateRequestOptions, Jn as SandboxFleetArtifact, Kn as SandboxEnvironment, L as CreateSandboxFleetOptions, On as ReapExpiredSandboxFleetsResult, Qn as SandboxFleetDispatchResponse, Qt as ListSandboxOptions, R as CreateSandboxFleetTokenOptions, St as FleetPromptDispatchOptions, Ti as TokenRefreshHandler, Tn as PublishPublicTemplateOptions, Ut as IntelligenceReport, Wn as SandboxClientConfig, Wt as IntelligenceReportBudget, Xn as SandboxFleetCostEstimate, Yn as SandboxFleetArtifactSpec, Zt as ListSandboxFleetOptions, _ as BatchResult, _n as PromptOptions, _t as FleetDispatchResultBufferOptions, a as AttachSandboxFleetMachineOptions, ar as SandboxFleetMachineRecord, br as SandboxFleetWorkspaceSnapshotResult, bt as FleetExecDispatchResult, ci as SshKeysManager, dr as SandboxFleetToken, fi as SubscriptionInfo, fr as SandboxFleetTraceBundle, g as BatchOptions, gn as PromptInputPart, gr as SandboxFleetUsage, gt as FleetDispatchResultBuffer, hr as SandboxFleetTraceOptions, ht as FleetDispatchCancelResult, ji as UsageInfo, kn as ReconcileSandboxFleetsOptions, lr as SandboxFleetOperationsSummary, m as BatchEvent, nt as ExecOptions, qr as SecretsManager, qt as IntelligenceReportWindow, rt as ExecResult, sr as SandboxFleetManifest, tr as SandboxFleetInfo, v as BatchRunOptions, vn as PromptResult, vr as SandboxFleetWorkspaceReconcileResult, vt as FleetDispatchStreamOptions, wn as PublicTemplateVersionInfo, x as BatchTask, xr as SandboxInfo, xt as FleetMachineId, y as BatchRunRequest, yr as SandboxFleetWorkspaceRestoreResult, yt as FleetExecDispatchOptions, z as CreateSandboxFleetWithCoordinatorOptions } from "./types-LNLeU9Ub.js";
+import { a as TraceExportSink, i as TraceExportResult, n as SandboxInstance, t as HttpClient } from "./sandbox-B9P4tyt4.js";
 
 //#region src/lib/sse-parser.d.ts
 /**
@@ -194,7 +194,11 @@ interface SessionBroadcastEvent {
   data?: unknown;
   channel?: string;
 }
-/** Result returned after Sandbox accepts or rejects a session event. */
+/**
+ * Result returned after Sandbox accepts or rejects a session event.
+ * For a session that has not connected yet, `success: true` means the event
+ * was durably queued for the authenticated owner.
+ */
 interface SessionBroadcastResult {
   success: boolean;
   sessionId: string;