@tangle-network/sandbox 0.10.5 → 0.11.0

package/dist/runtime.d.ts

@@ -1,6 +1,31 @@
-import { A as CommitTaskSessionOptions, B as CreateTaskSessionOptions, Dr as SandboxRuntimeHealth, Jr as SentSessionMessage, Kr as SendSessionMessageOptions, Mi as WriteFileOptions, Mr as SandboxTerminalInfo, Nr as SandboxTerminalManager, Pr as SandboxTerminalRequestOptions, Qr as SessionInfo, Sr as SandboxPortBinding, dt as FileTreeResult, ei as SessionMessage, ft as FileWriteResult, gi as TaskSessionInfo, it as FileReadBatchResult, jr as SandboxTerminalCreateOptions, kn as RenameOptions, kr as SandboxRuntimeProfileList, mi as TaskSessionCommitResult, pi as TaskSessionChanges, qr as SendSessionMessageRequest, qt as ListMessagesOptions, rt as FileReadBatchOptions, st as FileRenameResult, ut as FileTreeOptions, z as CreateSessionOptions } from "./types-BGGfKALh.js";
-import { a as NotFoundError, c as SandboxError, d as ServerError, f as StateError, i as NetworkError, l as SandboxErrorJson, m as ValidationError, n as CapabilityError, o as PartialFailureError, p as TimeoutError, s as QuotaError, t as AuthError, u as SandboxFailureDetail } from "./errors--P_nbLzM.js";
+import { Ar as SandboxRuntimeHealth, E as ChunkedUploadResult, Fi as WriteFileOptions, Fr as SandboxTerminalInfo, H as CreateTaskSessionOptions, Ir as SandboxTerminalManager, Lr as SandboxTerminalRequestOptions, M as CommitTaskSessionOptions, Mn as RenameOptions, Mr as SandboxRuntimeProfileList, Pr as SandboxTerminalCreateOptions, T as ChunkedUploadOptions, Tr as SandboxPortBinding, V as CreateSessionOptions, Xr as SendSessionMessageRequest, Xt as ListMessagesOptions, Yr as SendSessionMessageOptions, Zr as SentSessionMessage, _i as TaskSessionCommitResult, gi as TaskSessionChanges, ht as FileWriteResult, ji as UploadProgress, mt as FileTreeResult, ot as FileReadBatchOptions, pt as FileTreeOptions, ri as SessionMessage, st as FileReadBatchResult, ti as SessionInfo, ut as FileRenameResult, yi as TaskSessionInfo } from "./types-C4dFf5eL.js";
+import { a as NotFoundError, c as SandboxError, d as ServerError, f as StateError, i as NetworkError, l as SandboxErrorJson, m as ValidationError, n as CapabilityError, o as PartialFailureError, p as TimeoutError, s as QuotaError, t as AuthError, u as SandboxFailureDetail } from "./errors-ntvaf0_F.js";
 
+//#region src/lib/chunked-upload.d.ts
+/** The transport a caller wires this module to — {@link SandboxInstance.runtimeFetch}
+ *  in the SDK, or any fetch-shaped adapter in a standalone consumer. */
+interface ChunkedUploadTransport {
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Upload arbitrary binary or text data to the sandbox via the chunked
+ * upload-session protocol, verifying integrity with a whole-payload
+ * SHA-256 at commit. Browser/Worker-safe and works identically over the
+ * gateway proxy or a direct sidecar connection — see
+ * {@link FileSystem.uploadData}.
+ *
+ * @param transport - Fetch-shaped adapter scoped to the sandbox runtime
+ *   (paths are relative to it, e.g. `/fs/upload-session`).
+ * @param remotePath - Destination path in the sandbox.
+ * @param data - Payload to upload. Strings encode as UTF-8.
+ * @param options - See {@link ChunkedUploadOptions}.
+ * @throws {SandboxError} `PAYLOAD_TOO_LARGE` immediately (zero requests) if
+ *   the payload exceeds {@link FILE_UPLOAD_SESSION_MAX_BYTES}; otherwise the
+ *   typed error from whichever step (init/part/commit) failed after retries
+ *   are exhausted.
+ */
+declare function uploadChunked(transport: ChunkedUploadTransport, remotePath: string, data: Blob | ArrayBuffer | ArrayBufferView | string, options?: ChunkedUploadOptions): Promise<ChunkedUploadResult>;
+//#endregion
 //#region src/runtime-api.d.ts
 interface RuntimeTransport {
   ensureRunning(): Promise<void>;
@@ -16,6 +41,22 @@ declare class SandboxRuntimeApi {
   profiles(): Promise<SandboxRuntimeProfileList>;
   readFiles(paths: string[], options?: FileReadBatchOptions): Promise<FileReadBatchResult>;
   writeFile(path: string, content: string, options?: WriteFileOptions): Promise<FileWriteResult>;
+  /**
+   * Upload in-memory binary or text data to the sandbox over the chunked
+   * upload-session protocol — the browser/Worker-safe sanctioned path for
+   * payloads over ~1 MiB, sized to clear the gateway proxy's per-request cap
+   * (parts stay under {@link FILE_UPLOAD_PART_MAX_BYTES}). Binary-safe:
+   * accepts a `Blob`, `ArrayBuffer`, `ArrayBufferView`, or UTF-8 `string`.
+   * Delegates to the shared `uploadChunked` engine in `lib/chunked-upload.js`,
+   * wired to this client's `transport.fetch` so requests carry the same
+   * scoped-token `Authorization` header and base URL as every other method
+   * on this class (e.g. {@link SandboxRuntimeApi.writeFile}) — works
+   * identically over the gateway proxy or a direct sidecar connection.
+   *
+   * @throws {SandboxError} `PAYLOAD_TOO_LARGE` immediately, before any
+   *   request, if the payload exceeds the chunked-upload session cap.
+   */
+  uploadData(remotePath: string, data: Blob | ArrayBuffer | ArrayBufferView | string, options?: ChunkedUploadOptions): Promise<ChunkedUploadResult>;
   deleteFile(path: string, options?: Pick<WriteFileOptions, "sessionId">): Promise<void>;
   renameFile(sourcePath: string, destinationPath: string, options?: RenameOptions): Promise<FileRenameResult>;
   fileTree(path: string, options?: FileTreeOptions): Promise<FileTreeResult>;
@@ -37,9 +78,9 @@ declare class SandboxRuntimeApi {
 //#endregion
 //#region src/runtime-client.d.ts
 interface SandboxRuntimeClientConfig {
-  /** Browser-safe proxy base returned by `box.mintScopedToken()`. */
+  /** Browser-safe proxy base returned by a runtime-scoped token mint. */
   baseUrl: string;
-  /** Short-lived scoped token returned by `box.mintScopedToken()`. */
+  /** Short-lived `session-runtime` or `read-only` token. */
   token: string;
   /** Request timeout in milliseconds. Defaults to 30 seconds. */
   timeoutMs?: number;
@@ -50,7 +91,9 @@ interface SandboxRuntimeClientConfig {
  * Browser- and Worker-safe client for one sandbox runtime.
  *
  * Construct it from the scoped token response returned by
- * `box.mintScopedToken()`. The full Sandbox API key remains server-side.
+ * `box.mintScopedToken({ scope: "session-runtime", sessionId })` or
+ * `box.mintScopedToken({ scope: "read-only" })`. The full Sandbox API key
+ * remains server-side.
  */
 declare class SandboxRuntimeClient extends SandboxRuntimeApi {
   private readonly auth;
@@ -60,4 +103,4 @@ declare class SandboxRuntimeClient extends SandboxRuntimeApi {
 }
 declare function createSandboxRuntimeClient(config: SandboxRuntimeClientConfig): SandboxRuntimeClient;
 //#endregion
-export { AuthError, CapabilityError, type FileReadBatchOptions, type FileReadBatchResult, type FileRenameResult, type FileTreeOptions, type FileTreeResult, type FileWriteResult, type ListMessagesOptions, NetworkError, NotFoundError, PartialFailureError, QuotaError, type RenameOptions, SandboxError, type SandboxErrorJson, type SandboxFailureDetail, SandboxRuntimeClient, type SandboxRuntimeClientConfig, type SandboxRuntimeHealth, type SandboxTerminalCreateOptions, type SandboxTerminalInfo, type SandboxTerminalManager, type SandboxTerminalRequestOptions, ServerError, type SessionMessage, StateError, TimeoutError, ValidationError, type WriteFileOptions, createSandboxRuntimeClient };
+export { AuthError, CapabilityError, type ChunkedUploadOptions, type ChunkedUploadResult, type ChunkedUploadTransport, type FileReadBatchOptions, type FileReadBatchResult, type FileRenameResult, type FileTreeOptions, type FileTreeResult, type FileWriteResult, type ListMessagesOptions, NetworkError, NotFoundError, PartialFailureError, QuotaError, type RenameOptions, SandboxError, type SandboxErrorJson, type SandboxFailureDetail, SandboxRuntimeClient, type SandboxRuntimeClientConfig, type SandboxRuntimeHealth, type SandboxTerminalCreateOptions, type SandboxTerminalInfo, type SandboxTerminalManager, type SandboxTerminalRequestOptions, ServerError, type SessionMessage, StateError, TimeoutError, type UploadProgress, ValidationError, type WriteFileOptions, createSandboxRuntimeClient, uploadChunked };

package/dist/runtime.js

@@ -1,5 +1,5 @@
-import { t as SandboxRuntimeApi } from "./runtime-api-CvAUrnHc.js";
-import { a as NotFoundError, c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, o as PartialFailureError, s as QuotaError, t as AuthError, u as StateError } from "./errors-DSz87Rkk.js";
+import { o as combineAbortSignals, r as uploadChunked, t as SandboxRuntimeApi } from "./runtime-api-kukaWPtF.js";
+import { a as NotFoundError, c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, o as PartialFailureError, s as QuotaError, t as AuthError, u as StateError } from "./errors-Cbs78OlF.js";
 //#region src/runtime-client.ts
 const DEFAULT_RUNTIME_TIMEOUT_MS = 3e4;
 function requireToken(token) {
@@ -28,7 +28,9 @@ function requireTimeout(timeoutMs) {
 * Browser- and Worker-safe client for one sandbox runtime.
 *
 * Construct it from the scoped token response returned by
-* `box.mintScopedToken()`. The full Sandbox API key remains server-side.
+* `box.mintScopedToken({ scope: "session-runtime", sessionId })` or
+* `box.mintScopedToken({ scope: "read-only" })`. The full Sandbox API key
+* remains server-side.
 */
 var SandboxRuntimeClient = class extends SandboxRuntimeApi {
 	auth;
@@ -47,7 +49,7 @@ var SandboxRuntimeClient = class extends SandboxRuntimeApi {
 				const isFormData = typeof FormData !== "undefined" && init.body instanceof FormData;
 				if (init.body !== void 0 && !isFormData && !headers.has("Content-Type")) headers.set("Content-Type", "application/json");
 				const timeoutSignal = AbortSignal.timeout(timeoutMs);
-				const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+				const signal = init.signal ? combineAbortSignals([init.signal, timeoutSignal]) : timeoutSignal;
 				try {
 					return await fetchImpl(`${baseUrl}${path}`, {
 						...init,
@@ -78,4 +80,4 @@ function createSandboxRuntimeClient(config) {
 	return new SandboxRuntimeClient(config);
 }
 //#endregion
-export { AuthError, CapabilityError, NetworkError, NotFoundError, PartialFailureError, QuotaError, SandboxError, SandboxRuntimeClient, ServerError, StateError, TimeoutError, ValidationError, createSandboxRuntimeClient };
+export { AuthError, CapabilityError, NetworkError, NotFoundError, PartialFailureError, QuotaError, SandboxError, SandboxRuntimeClient, ServerError, StateError, TimeoutError, ValidationError, createSandboxRuntimeClient, uploadChunked };

package/dist/{sandbox-tksuLdrT.d.ts → sandbox-BSsCz6nP.d.ts}

@@ -1,4 +1,4 @@
-import { $ as EventStreamOptions, $r as SessionListOptions, A as CommitTaskSessionOptions, Ai as WaitForOptions, An as RestoreSnapshotOptions, Ar as SandboxStatus, B as CreateTaskSessionOptions, Bn as SSHCommandDescriptor, Br as ScopedToken, Bt as InstalledTool, D as CodeLanguage, Dr as SandboxRuntimeHealth, Dt as GitDiff, E as CodeExecutionResult, Fr as SandboxTraceBundle, Gn as SandboxEvent, Gt as IntelligenceReportWindow, Hr as SearchMatch, Ht as IntelligenceReportBudget, In as RolloutStartResult, Jr as SentSessionMessage, Kr as SendSessionMessageOptions, Kt as JsonValue, Mi as WriteFileOptions, Mn as Rollout, Ni as WriteManyFile, Nr as SandboxTerminalManager, Ot as GitStatus, Pi as WriteManyOptions, Pn as RolloutOptions, Pt as GpuLeaseManager, Qr as SessionInfo, Qt as MintScopedTokenOptions, Rr as SandboxTraceOptions, Si as TeePublicKeyResponse, Sr as SandboxPortBinding, T as CodeExecutionOptions, Ti as TurnDriveResult, Tr as SandboxResourceUsage, Tt as GitCommit, U as DispatchPromptOptions, Un as SandboxConnection, Ur as SearchOptions, Ut as IntelligenceReportCompareTo, Vn as SSHCredentials, Vt as IntelligenceReport, W as DispatchedSession, Xr as SessionEventStreamOptions, Y as DriverInfo, Z as EgressManager, Zr as SessionForkOptions, _n as ProvisionEvent, ai as SnapshotResult, bi as TeeAttestationResponse, ct as FileSystem, di as TaskOptions, ei as SessionMessage, et as ExecOptions, fi as TaskResult, ft as FileWriteResult, gi as TaskSessionInfo, gn as PromptResult, hn as PromptOptions, ii as SnapshotOptions, in as PermissionsManager, j as CompletedTurnResult, ji as WaitForRolloutOptions, jn as ResumeOptions, kr as SandboxRuntimeProfileList, kt as GpuLease, l as BackendManager, mi as TaskSessionCommitResult, mn as PromptInputPart, on as PreviewLinkManager, pi as TaskSessionChanges, q as DriveTurnOptions, qr as SendSessionMessageRequest, qt as ListMessagesOptions, ri as SnapshotInfo, s as BackendConfig, si as StartupDiagnostics, tn as NetworkManager, tt as ExecResult, un as ProcessManager, ur as SandboxFleetTraceBundle, vi as TeeAttestationOptions, vn as ProvisionResult, w as BranchOptions, wt as GitBranch, yr as SandboxInfo, z as CreateSessionOptions } from "./types-BGGfKALh.js";
+import { $ as DurablePlan, $r as SessionEventStreamOptions, Ar as SandboxRuntimeHealth, At as GitDiff, Ci as TeeAttestationResponse, D as CodeExecutionOptions, Dt as GitBranch, Fi as WriteFileOptions, Fn as Rollout, G as DispatchPromptOptions, Gr as SearchMatch, Gt as IntelligenceReportBudget, H as CreateTaskSessionOptions, Ii as WriteManyFile, Ir as SandboxTerminalManager, Jn as SandboxEvent, Jt as IntelligenceReportWindow, K as DispatchedSession, Kn as SandboxConnection, Kr as SearchOptions, Kt as IntelligenceReportCompareTo, Li as WriteManyOptions, Ln as RolloutOptions, Lt as GpuLeaseManager, M as CommitTaskSessionOptions, Mr as SandboxRuntimeProfileList, Mt as GpuLease, N as CompletedTurnResult, Ni as WaitForOptions, Nn as RestoreSnapshotOptions, Nr as SandboxStatus, O as CodeExecutionResult, Oi as TurnDriveResult, Or as SandboxResourceUsage, Ot as GitCommit, Pi as WaitForRolloutOptions, Pn as ResumeOptions, Rr as SandboxTraceBundle, Sr as SandboxInfo, Ti as TeePublicKeyResponse, Tr as SandboxPortBinding, Un as SSHCommandDescriptor, Ur as ScopedToken, Ut as InstalledTool, V as CreateSessionOptions, Vr as SandboxTraceOptions, Wn as SSHCredentials, Wt as IntelligenceReport, Xr as SendSessionMessageRequest, Xt as ListMessagesOptions, Y as DriveTurnOptions, Yr as SendSessionMessageOptions, Yt as JsonValue, Z as DriverInfo, Zr as SentSessionMessage, _i as TaskSessionCommitResult, _n as PromptInputPart, bn as ProvisionEvent, ci as SnapshotResult, dt as FileSystem, ei as SessionForkOptions, et as EgressManager, gi as TaskSessionChanges, hi as TaskResult, ht as FileWriteResult, in as NetworkManager, it as ExecResult, jt as GitStatus, k as CodeLanguage, l as BackendManager, ln as PreviewLinkManager, mi as TaskOptions, ni as SessionListOptions, nt as EventStreamOptions, oi as SnapshotInfo, pn as ProcessManager, pr as SandboxFleetTraceBundle, ri as SessionMessage, rt as ExecOptions, s as BackendConfig, si as SnapshotOptions, sn as PermissionsManager, ti as SessionInfo, tn as MintScopedTokenOptions, ui as StartupDiagnostics, vn as PromptOptions, w as BranchOptions, xi as TeeAttestationOptions, xn as ProvisionResult, yi as TaskSessionInfo, yn as PromptResult, zn as RolloutStartResult } from "./types-C4dFf5eL.js";
 
 //#region src/mcp.d.ts
 /**
@@ -221,6 +221,13 @@ interface SandboxSessionHost extends InteractiveSessionHost {
   _respondToPermission(id: string, permissionID: string, options: RespondToPermissionOptions): Promise<void>;
   _interrupt(id: string): Promise<InterruptResult>;
   _answerQuestion(id: string, answers: Record<string, string[]>): Promise<void>;
+  _currentPlan(id: string): Promise<DurablePlan | null>;
+  _decidePlan(id: string, planId: string, decision: {
+    outcome: "approved";
+  } | {
+    outcome: "rejected";
+    feedback: string;
+  }): Promise<DurablePlan>;
 }
 /**
  * A single agent session inside a sandbox. Created via
@@ -327,6 +334,13 @@ declare class SandboxSession {
    * enabled. Backends with no question support reject loudly.
    */
   answer(answers: Record<string, string[]>): Promise<void>;
+  /** Return the newest plan awaiting a decision for this session. */
+  plan(): Promise<DurablePlan | null>;
+  /** Approve a durable plan and enqueue its separate execution turn. */
+  approvePlan(planId?: string): Promise<DurablePlan>;
+  /** Reject a durable plan with required feedback and enqueue a revision turn. */
+  rejectPlan(feedback: string, planId?: string): Promise<DurablePlan>;
+  private requireCurrentPlan;
 }
 //#endregion
 //#region src/task-session.d.ts
@@ -894,6 +908,11 @@ declare class SandboxInstance {
   private fsReadBatch;
   private fsTree;
   private fsUpload;
+  /** See {@link FileSystem.uploadData}. Delegates to the shared, browser-safe
+   *  chunked-upload flow in `lib/chunked-upload.ts`, wired to this sandbox's
+   *  runtime endpoint (works over the gateway proxy or a direct connection —
+   *  both are transparent through `runtimeFetch`). */
+  private fsUploadData;
   private fsDownload;
   private fsUploadDir;
   private fsDownloadDir;
@@ -1015,7 +1034,6 @@ declare class SandboxInstance {
    * ```
    */
   get process(): ProcessManager;
-  private processSpawnExact;
   private processSpawn;
   private processRunCode;
   private processList;
@@ -1500,21 +1518,16 @@ declare class SandboxInstance {
    */
   driveTurn(message: string | PromptInputPart[], opts: DriveTurnOptions): Promise<TurnDriveResult>;
   /**
-   * Mint a scoped, time-bounded JWT for direct browser access to this
-   * sandbox (Issue #913 Gap 1). Authority is the caller's
-   * `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
-   * signing secrets stay server-side.
-   *
-   * Use this to give a browser direct read access to the sandbox without
-   * leaking the full bearer (`box.connection.authToken`). The returned
-   * token verifies against the same sidecar middleware that already
-   * gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
+   * Mint a scoped, time-bounded JWT for browser access (Issue #913 Gap 1).
+   * Authority is the caller's `TANGLE_API_KEY` (sk-tan-*); signing secrets
+   * stay server-side. Session/project scopes work with SessionGatewayClient,
+   * while session-runtime/read-only scopes work with SandboxRuntimeClient.
    */
   mintScopedToken(opts: MintScopedTokenOptions): Promise<ScopedToken>;
   /** @internal — invoked by SandboxSession.status(). */
   _sessionStatus(id: string): Promise<SessionInfo | null>;
   /** @internal — invoked by SandboxSession.events(). */
-  _sessionEvents(id: string, opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
+  _sessionEvents(id: string, opts?: SessionEventStreamOptions, stopOnTurnTerminal?: boolean): AsyncGenerator<SandboxEvent>;
   /** @internal — invoked by SandboxSession.result(). */
   _sessionResult(id: string): Promise<PromptResult>;
   /**
@@ -1542,6 +1555,15 @@ declare class SandboxInstance {
    * question's `answerSpec` fields in order.
    */
   _answerQuestion(id: string, answers: Record<string, string[]>): Promise<void>;
+  /** @internal — invoked by SandboxSession.plan(). */
+  _currentPlan(sessionId: string): Promise<DurablePlan | null>;
+  /** @internal — invoked by SandboxSession.approvePlan()/rejectPlan(). */
+  _decidePlan(sessionId: string, planId: string, decision: {
+    outcome: "approved";
+  } | {
+    outcome: "rejected";
+    feedback: string;
+  }): Promise<DurablePlan>;
 }
 //#endregion
 export { SandboxMcpConfig as C, buildSandboxMcpConfig as D, buildControlPlaneMcpConfig as E, SANDBOX_MCP_SERVER_NAME as S, SandboxMcpServerEntry as T, RespondToPermissionOptions as _, TraceExportSink as a, BuildSandboxMcpConfigOptions as b, otelTraceIdForTangleTrace as c, SandboxSession as d, InteractiveAuthFile as f, InterruptResult as g, InteractiveSessionInfo as h, TraceExportResult as i, toOtelJson as l, InteractiveSessionHost as m, SandboxInstance as n, buildTraceExportPayload as o, InteractiveSessionHandle as p, TraceExportFormat as r, exportTraceBundle as s, HttpClient as t, SandboxTaskSession as u, StartInteractiveOptions as v, SandboxMcpEndpoint as w, CONTROL_PLANE_MCP_SERVER_NAME as x, BuildControlPlaneMcpConfigOptions as y };