@tangle-network/sandbox 0.0.0-develop.20260610125345.cbdf7b2 → 0.0.0-develop.20260610200051.84d8326

package/dist/{sandbox-CqlT4WnD.d.ts → sandbox-BQbq1EGP.d.ts}

@@ -668,6 +668,16 @@ interface CreateSandboxOptions {
    * ```
    */
   network?: NetworkConfig;
+  /**
+   * Egress firewall policy for controlling outbound internet access.
+   *
+   * When omitted on a team sandbox, the team's default egress policy is
+   * inherited. When omitted on a personal sandbox, the platform default
+   * (`{ mode: "open" }`) is used.
+   *
+   * @see {@link EgressPolicy}
+   */
+  egressPolicy?: EgressPolicy;
   /**
    * Git repository to clone at sandbox creation.
    *
@@ -956,6 +966,10 @@ interface SandboxInfo {
   expiresAt?: Date;
   /** Error message if status is 'failed' */
   error?: string;
+  /** Resolved egress policy */
+  egressPolicy?: EgressPolicy;
+  /** Source of the egress policy */
+  egressPolicySource?: "sandbox" | "team" | "platform";
 }
 /**
  * Raw TEE attestation evidence returned by the sandbox runtime.
@@ -1768,6 +1782,53 @@ interface DispatchedSession {
    * dispatch was a no-op (idempotency). */
   alreadyExisted: boolean;
 }
+/**
+ * Options for `box.driveTurn()` — one settle/poll/dispatch pass over a
+ * detached turn. Inherits the full prompt surface (`backend`, `model`,
+ * `turnId`, …) so the dispatch leg configures the run exactly like
+ * `box.dispatchPrompt()` would.
+ */
+interface DriveTurnOptions extends DispatchPromptOptions {
+  /** Deterministic session id — required, it is the resume key. Every
+   * tick for the same logical turn MUST pass the same id so a re-invoke
+   * after a crash finds the in-flight session instead of starting a
+   * second agent run. */
+  sessionId: string;
+  /** Turn idempotency key for the platform's completed-turn cache.
+   * Defaults to `sessionId`, which is correct for the one-turn-per-
+   * session shape detached drivers use. */
+  turnId?: string;
+  /** Wall-clock cap in milliseconds, measured from the session's
+   * `startedAt` (falling back to `createdAt`). When a still-running
+   * session exceeds it, `driveTurn` cancels the session and reports
+   * `state: "failed"` — bounding unattended runs that would otherwise
+   * stall forever (e.g. an interactive question nothing will answer).
+   * Omit for no cap. */
+  wallCapMs?: number;
+}
+/**
+ * Returned by `box.driveTurn()` — where the detached turn stands after
+ * one pass. Discriminated on `state`:
+ *   - `completed` — the turn finished with a text payload; `result` is
+ *     the full cached AgentExecutionResult-shape record.
+ *   - `running` — the session is queued or executing; re-invoke after a
+ *     delay of your choosing.
+ *   - `failed` — terminal and deterministic: a failed/cancelled session,
+ *     a wall-cap cancellation, or a completed turn that carried no text.
+ *     Re-invoking will not change the outcome.
+ */
+type TurnDriveResult = {
+  state: "completed"; /** Final assistant text of the turn. */
+  text: string; /** The full turn payload (text, toolInvocations, tokenUsage, etc.). */
+  result: Record<string, unknown>;
+} | {
+  state: "running"; /** When the session began executing, if the runtime reported it. */
+  startedAt?: Date; /** Milliseconds since `startedAt` at the moment of the poll. */
+  elapsedMs?: number;
+} | {
+  state: "failed"; /** Human-readable reason the turn is deterministically failed. */
+  error: string;
+};
 /**
  * Scope of a `box.mintScopedToken()` request. Each value narrows the
  * token's authority compared to the full sandbox bearer.
@@ -2669,13 +2730,14 @@ interface DriverInfo {
  * - `"hermes"` — Hermes inference-router agent.
  * - `"forge"` — Forge (forgecode.dev, tailcallhq) multi-provider coding agent.
  * - `"openclaw"` — OpenClaw dispatcher that routes to claude-cli/codex-cli/gemini-cli.
+ * - `"nanoclaw"` — NanoClaw local socket bridge backend.
  * - `"acp"` — Agent Client Protocol bridge — fronts any ACP-compliant
  *   agent binary (claude-agent-acp, codex-acp, gemini, openclaw acp).
  *   Pick the backing agent via config.subAgent.
  * - `"cursor"` — Cursor Agent SDK local/cloud backend.
  * - `"cli-base"` — Minimal CLI-only (no AI agent).
  */
-type BackendType = "opencode" | "claude-code" | "kimi-code" | "codex" | "amp" | "factory-droids" | "pi" | "hermes" | "forge" | "openclaw" | "acp" | "cursor" | "cli-base";
+type BackendType = "opencode" | "claude-code" | "kimi-code" | "codex" | "amp" | "factory-droids" | "pi" | "hermes" | "forge" | "openclaw" | "nanoclaw" | "acp" | "cursor" | "cli-base";
 /**
  * MCP (Model Context Protocol) server configuration.
  */
@@ -2924,6 +2986,89 @@ interface NetworkConfig {
    */
   ports?: number[];
 }
+/**
+ * Egress firewall policy for controlling outbound internet access.
+ *
+ * Applied at sandbox creation and mutable at runtime via `box.egress.update()`.
+ * The policy is enforced by the sandbox-side iron-proxy (layer-7 HTTP/HTTPS
+ * filter) and is independent of `network` (which controls layer-3/4 rules).
+ *
+ * @example Open mode — default, all outbound allowed
+ * ```typescript
+ * egressPolicy: { mode: "open" }
+ * ```
+ *
+ * @example Strict mode — only allowlisted domains
+ * ```typescript
+ * egressPolicy: {
+ *   mode: "strict",
+ *   allowDomains: ["api.github.com", "pypi.org"],
+ * }
+ * ```
+ *
+ * @example Blocked mode — no outbound internet
+ * ```typescript
+ * egressPolicy: { mode: "blocked" }
+ * ```
+ */
+interface EgressPolicy {
+  /** Egress mode */
+  mode: "open" | "strict" | "blocked";
+  /**
+   * Additional allowed domains in strict mode.
+   * These are merged with the platform default allowlist.
+   * Ignored in `open` and `blocked` modes.
+   */
+  allowDomains?: string[];
+  /**
+   * Denied domains. Only enforced when the proxy supports denylist transforms.
+   * @deprecated Deferred — not supported by iron-proxy v0.41.
+   */
+  denyDomains?: string[];
+  /**
+   * Allowed CIDR ranges. Only enforced when the proxy supports CIDR passthrough.
+   * @deprecated Deferred — not supported by iron-proxy v0.41.
+   */
+  allowCidrs?: string[];
+}
+/**
+ * Egress policy manager for runtime egress configuration.
+ * Access via `sandbox.egress`.
+ *
+ * @example Read current egress policy
+ * ```typescript
+ * const policy = await box.egress.get();
+ * console.log(policy.mode); // "open" | "strict" | "blocked"
+ * ```
+ *
+ * @example Update egress policy at runtime
+ * ```typescript
+ * await box.egress.update({ mode: "strict", allowDomains: ["api.github.com"] });
+ * ```
+ */
+interface EgressManager {
+  /**
+   * Get the sandbox's current egress policy.
+   *
+   * @returns Resolved egress policy and its source
+   */
+  get(): Promise<{
+    policy: EgressPolicy;
+    source: "sandbox" | "team" | "platform";
+  }>;
+  /**
+   * Update the sandbox's egress policy at runtime.
+   *
+   * The proxy container is restarted to apply the new policy (~2–5s downtime).
+   *
+   * @param policy - New egress policy to apply
+   * @returns Updated policy and source
+   */
+  update(policy: EgressPolicy): Promise<{
+    policy: EgressPolicy;
+    source: "sandbox" | "team" | "platform";
+  }>;
+}
 /**
  * Network manager for runtime network configuration.
  * Access via `sandbox.network`.
@@ -4806,10 +4951,27 @@ declare class SandboxInstance {
    * ```
    */
   get network(): NetworkManager;
+  /**
+   * Egress policy manager for controlling outbound internet access.
+   *
+   * @example Read current egress policy
+   * ```typescript
+   * const { policy, source } = await box.egress.get();
+   * console.log(policy.mode, source);
+   * ```
+   *
+   * @example Update egress policy at runtime
+   * ```typescript
+   * await box.egress.update({ mode: "strict", allowDomains: ["api.github.com"] });
+   * ```
+   */
+  get egress(): EgressManager;
   private networkUpdate;
   private networkExposePort;
   private networkListUrls;
   private networkGetConfig;
+  private egressGet;
+  private egressUpdate;
   /**
    * Validate CIDR notation (IPv4 and IPv6)
    */
@@ -5161,6 +5323,31 @@ declare class SandboxInstance {
   findCompletedTurn(turnId: string, opts: {
     sessionId: string;
   }): Promise<CompletedTurnResult | null>;
+  /**
+   * Drive a detached turn forward by exactly one settle → poll → dispatch
+   * pass and report where it stands. Built for tick-based callers —
+   * Cloudflare Workflows steps, queue consumers, crons — that re-invoke
+   * on their own schedule instead of holding a stream open. One
+   * invocation never loops, never sleeps, and never keeps a connection
+   * alive past the pass.
+   *
+   * The pass resolves to the first of:
+   *   1. The completed-turn cache has `turnId` → `completed`, or `failed`
+   *      when the cached payload carries no text — that result is final,
+   *      so a retry cannot improve it.
+   *   2. The session is queued/running → `running`, after enforcing
+   *      `wallCapMs`: a session past the cap is cancelled and reported
+   *      `failed`.
+   *   3. The session is terminal without a cached turn → settle from the
+   *      session result; an unsuccessful result is `failed`.
+   *   4. No session exists → dispatch fire-and-detach (idempotent on
+   *      `sessionId`, exactly like `dispatchPrompt`) → `running`.
+   *
+   * `failed` is always deterministic: re-invoking with the same ids
+   * returns the same outcome rather than starting a second agent run, so
+   * callers can treat it as terminal without their own retry bookkeeping.
+   */
+  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
@@ -5183,4 +5370,4 @@ declare class SandboxInstance {
   _sessionCancel(id: string): Promise<void>;
 }
 //#endregion
-export { DispatchedSession as $, SandboxStatus as $n, ProcessStatus as $t, BatchEvent as A, SandboxFleetIntelligenceEnvelope as An, ToolsConfig as Ar, IntelligenceReportBudget as At, CodeLanguage as B, SandboxFleetTraceBundle as Bn, AgentProfileMcpServer as Br, MkdirOptions as Bt, AttachSandboxFleetMachineOptions as C, SandboxFleetArtifactSpec as Cn, TaskResult as Cr, GitCommit as Ct, BackendManager as D, SandboxFleetDriverCapability as Dn, TeePublicKey as Dr, GpuType as Dt, BackendInfo as E, SandboxFleetDispatchResponse as En, TeeAttestationResponse as Er, GitStatus as Et, CheckpointInfo as F, SandboxFleetManifest as Fn, WaitForOptions as Fr, ListOptions as Ft, CreateRequestOptions as G, SandboxFleetWorkspace as Gn, AgentProfileResources as Gr, PreviewLinkInfo as Gt, CodeResultPart as H, SandboxFleetTraceExport as Hn, AgentProfilePermissionValue as Hr, NetworkManager as Ht, CheckpointOptions as I, SandboxFleetManifestMachine as In, AgentProfile as Ir, ListSandboxFleetOptions as It, CreateSandboxFleetWithCoordinatorOptions as J, SandboxFleetWorkspaceSnapshotResult as Jn, AgentSubagentProfile as Jr, ProcessInfo as Jt, CreateSandboxFleetOptions as K, SandboxFleetWorkspaceReconcileResult as Kn, AgentProfileValidationIssue as Kr, PreviewLinkManager as Kt, CheckpointResult as L, SandboxFleetOperationsSummary as Ln, AgentProfileCapabilities as Lr, ListSandboxOptions as Lt, BatchResult as M, SandboxFleetMachineMeteredUsage as Mn, UploadOptions as Mr, IntelligenceReportSubjectType as Mt, BatchTask as N, SandboxFleetMachineRecord as Nn, UploadProgress as Nr, IntelligenceReportWindow as Nt, BackendStatus as O, SandboxFleetDriverTimings as On, TeePublicKeyResponse as Or, InstalledTool as Ot, BatchTaskResult as P, SandboxFleetMachineSpec as Pn, UsageInfo as Pr, ListMessagesOptions as Pt, DispatchPromptOptions as Q, SandboxResources as Qn, mergeAgentProfiles as Qr, ProcessSpawnOptions as Qt, CodeExecutionOptions as R, SandboxFleetPolicy as Rn, AgentProfileConfidential as Rr, McpServerConfig as Rt, AddUserOptions as S, SandboxFleetArtifact as Sn, TaskOptions as Sr, GitBranch as St, BackendConfig as T, SandboxFleetDispatchFailureClass as Tn, TeeAttestationReport as Tr, GitDiff as Tt, CompletedTurnResult as U, SandboxFleetTraceOptions as Un, AgentProfilePrompt as Ur, PermissionLevel as Ut, CodeResult as V, SandboxFleetTraceEvent as Vn, AgentProfileModelHints as Vr, NetworkConfig as Vt, CreateIntelligenceReportOptions as W, SandboxFleetUsage as Wn, AgentProfileResourceRef as Wr, PermissionsManager as Wt, DeleteOptions as X, SandboxIntelligenceEnvelope as Xn, defineGitHubResource as Xr, ProcessManager as Xt, CreateSandboxOptions as Y, SandboxInfo as Yn, defineAgentProfile as Yr, ProcessLogEntry as Yt, DirectoryPermission as Z, SandboxPermissionsConfig as Zn, defineInlineResource as Zr, ProcessSignal as Zt, SandboxMcpServerEntry as _, SSHCredentials as _n, SnapshotOptions as _r, FleetPromptDispatchOptions as _t, TraceExportSink as a, ProvisionStatus as an, ScopedToken as ar, EventStreamOptions as at, AcceleratorKind as b, SandboxEnvironment as bn, StorageConfig as br, ForkResult as bt, otelTraceIdForTangleTrace as c, PublicTemplateVersionInfo as cn, SearchOptions as cr, FileInfo as ct, BuildControlPlaneMcpConfigOptions as d, ReapExpiredSandboxFleetsOptions as dn, SessionEventStreamOptions as dr, FleetDispatchResultBuffer as dt, PromptInputPart as en, SandboxTraceBundle as er, DownloadOptions as et, BuildSandboxMcpConfigOptions as f, ReapExpiredSandboxFleetsResult as fn, SessionInfo as fr, FleetDispatchResultBufferOptions as ft, SandboxMcpEndpoint as g, SSHCommandDescriptor as gn, SnapshotInfo as gr, FleetMachineId as gt, SandboxMcpConfig as h, RunCodeOptions as hn, SessionStatus as hr, FleetExecDispatchResult as ht, TraceExportResult as i, ProvisionResult as in, SandboxUser as ir, DriverType as it, BatchOptions as j, SandboxFleetMachine as jn, UpdateUserOptions as jr, IntelligenceReportCompareTo as jt, BackendType as k, SandboxFleetInfo as kn, TokenRefreshHandler as kr, IntelligenceReport as kt, toOtelJson as l, PublishPublicTemplateOptions as ln, SecretInfo as lr, FileSystem as lt, SANDBOX_MCP_SERVER_NAME as m, ReconcileSandboxFleetsResult as mn, SessionMessage as mr, FleetExecDispatchOptions as mt, SandboxInstance as n, PromptResult as nn, SandboxTraceExport as nr, DriverConfig as nt, buildTraceExportPayload as o, ProvisionStep as on, ScopedTokenScope as or, ExecOptions as ot, CONTROL_PLANE_MCP_SERVER_NAME as p, ReconcileSandboxFleetsOptions as pn, SessionListOptions as pr, FleetDispatchStreamOptions as pt, CreateSandboxFleetTokenOptions as q, SandboxFleetWorkspaceRestoreResult as qn, AgentProfileValidationResult as qr, Process as qt, TraceExportFormat as r, ProvisionEvent as rn, SandboxTraceOptions as rr, DriverInfo as rt, exportTraceBundle as s, PublicTemplateInfo as sn, SearchMatch as sr, ExecResult as st, HttpClient as t, PromptOptions as tn, SandboxTraceEvent as tr, DownloadProgress as tt, SandboxSession as u, PublishPublicTemplateVersionOptions as un, SecretsManager as ur, FleetDispatchCancelResult as ut, buildControlPlaneMcpConfig as v, SandboxClientConfig as vn, SnapshotResult as vr, FleetPromptDispatchResult as vt, BackendCapabilities as w, SandboxFleetCostEstimate as wn, TeeAttestationOptions as wr, GitConfig as wt, AccessPolicyRule as x, SandboxEvent as xn, SubscriptionInfo as xr, GitAuth as xt, buildSandboxMcpConfig as y, SandboxConnection as yn, SshKeysManager as yr, ForkOptions as yt, CodeExecutionResult as z, SandboxFleetToken as zn, AgentProfileFileMount as zr, MintScopedTokenOptions as zt };
+export { DispatchedSession as $, SandboxIntelligenceEnvelope as $n, defineAgentProfile as $r, ProcessManager as $t, BatchEvent as A, SandboxFleetDriverCapability as An, TeePublicKey as Ar, GpuType as At, CodeLanguage as B, SandboxFleetOperationsSummary as Bn, AgentProfile as Br, ListSandboxOptions as Bt, AttachSandboxFleetMachineOptions as C, SandboxEnvironment as Cn, StorageConfig as Cr, ForkResult as Ct, BackendManager as D, SandboxFleetCostEstimate as Dn, TeeAttestationOptions as Dr, GitConfig as Dt, BackendInfo as E, SandboxFleetArtifactSpec as En, TaskResult as Er, GitCommit as Et, CheckpointInfo as F, SandboxFleetMachineMeteredUsage as Fn, UpdateUserOptions as Fr, IntelligenceReportSubjectType as Ft, CreateRequestOptions as G, SandboxFleetTraceExport as Gn, AgentProfileModelHints as Gr, NetworkManager as Gt, CodeResultPart as H, SandboxFleetToken as Hn, AgentProfileConfidential as Hr, MintScopedTokenOptions as Ht, CheckpointOptions as I, SandboxFleetMachineRecord as In, UploadOptions as Ir, IntelligenceReportWindow as It, CreateSandboxFleetWithCoordinatorOptions as J, SandboxFleetWorkspace as Jn, AgentProfileResourceRef as Jr, PreviewLinkInfo as Jt, CreateSandboxFleetOptions as K, SandboxFleetTraceOptions as Kn, AgentProfilePermissionValue as Kr, PermissionLevel as Kt, CheckpointResult as L, SandboxFleetMachineSpec as Ln, UploadProgress as Lr, ListMessagesOptions as Lt, BatchResult as M, SandboxFleetInfo as Mn, TokenRefreshHandler as Mr, IntelligenceReport as Mt, BatchTask as N, SandboxFleetIntelligenceEnvelope as Nn, ToolsConfig as Nr, IntelligenceReportBudget as Nt, BackendStatus as O, SandboxFleetDispatchFailureClass as On, TeeAttestationReport as Or, GitDiff as Ot, BatchTaskResult as P, SandboxFleetMachine as Pn, TurnDriveResult as Pr, IntelligenceReportCompareTo as Pt, DispatchPromptOptions as Q, SandboxInfo as Qn, AgentSubagentProfile as Qr, ProcessLogEntry as Qt, CodeExecutionOptions as R, SandboxFleetManifest as Rn, UsageInfo as Rr, ListOptions as Rt, AddUserOptions as S, SandboxConnection as Sn, SshKeysManager as Sr, ForkOptions as St, BackendConfig as T, SandboxFleetArtifact as Tn, TaskOptions as Tr, GitBranch as Tt, CompletedTurnResult as U, SandboxFleetTraceBundle as Un, AgentProfileFileMount as Ur, MkdirOptions as Ut, CodeResult as V, SandboxFleetPolicy as Vn, AgentProfileCapabilities as Vr, McpServerConfig as Vt, CreateIntelligenceReportOptions as W, SandboxFleetTraceEvent as Wn, AgentProfileMcpServer as Wr, NetworkConfig as Wt, DeleteOptions as X, SandboxFleetWorkspaceRestoreResult as Xn, AgentProfileValidationIssue as Xr, Process as Xt, CreateSandboxOptions as Y, SandboxFleetWorkspaceReconcileResult as Yn, AgentProfileResources as Yr, PreviewLinkManager as Yt, DirectoryPermission as Z, SandboxFleetWorkspaceSnapshotResult as Zn, AgentProfileValidationResult as Zr, ProcessInfo as Zt, SandboxMcpServerEntry as _, ReconcileSandboxFleetsResult as _n, SessionMessage as _r, FleetExecDispatchOptions as _t, TraceExportSink as a, PromptResult as an, SandboxTraceExport as ar, DriverType as at, AcceleratorKind as b, SSHCredentials as bn, SnapshotOptions as br, FleetPromptDispatchOptions as bt, otelTraceIdForTangleTrace as c, ProvisionStatus as cn, ScopedToken as cr, EventStreamOptions as ct, BuildControlPlaneMcpConfigOptions as d, PublicTemplateVersionInfo as dn, SearchOptions as dr, FileInfo as dt, defineGitHubResource as ei, ProcessSignal as en, SandboxPermissionsConfig as er, DownloadOptions as et, BuildSandboxMcpConfigOptions as f, PublishPublicTemplateOptions as fn, SecretInfo as fr, FileSystem as ft, SandboxMcpEndpoint as g, ReconcileSandboxFleetsOptions as gn, SessionListOptions as gr, FleetDispatchStreamOptions as gt, SandboxMcpConfig as h, ReapExpiredSandboxFleetsResult as hn, SessionInfo as hr, FleetDispatchResultBufferOptions as ht, TraceExportResult as i, PromptOptions as in, SandboxTraceEvent as ir, DriverInfo as it, BatchOptions as j, SandboxFleetDriverTimings as jn, TeePublicKeyResponse as jr, InstalledTool as jt, BackendType as k, SandboxFleetDispatchResponse as kn, TeeAttestationResponse as kr, GitStatus as kt, toOtelJson as l, ProvisionStep as ln, ScopedTokenScope as lr, ExecOptions as lt, SANDBOX_MCP_SERVER_NAME as m, ReapExpiredSandboxFleetsOptions as mn, SessionEventStreamOptions as mr, FleetDispatchResultBuffer as mt, SandboxInstance as n, mergeAgentProfiles as ni, ProcessStatus as nn, SandboxStatus as nr, DriveTurnOptions as nt, buildTraceExportPayload as o, ProvisionEvent as on, SandboxTraceOptions as or, EgressManager as ot, CONTROL_PLANE_MCP_SERVER_NAME as p, PublishPublicTemplateVersionOptions as pn, SecretsManager as pr, FleetDispatchCancelResult as pt, CreateSandboxFleetTokenOptions as q, SandboxFleetUsage as qn, AgentProfilePrompt as qr, PermissionsManager as qt, TraceExportFormat as r, PromptInputPart as rn, SandboxTraceBundle as rr, DriverConfig as rt, exportTraceBundle as s, ProvisionResult as sn, SandboxUser as sr, EgressPolicy as st, HttpClient as t, defineInlineResource as ti, ProcessSpawnOptions as tn, SandboxResources as tr, DownloadProgress as tt, SandboxSession as u, PublicTemplateInfo as un, SearchMatch as ur, ExecResult as ut, buildControlPlaneMcpConfig as v, RunCodeOptions as vn, SessionStatus as vr, FleetExecDispatchResult as vt, BackendCapabilities as w, SandboxEvent as wn, SubscriptionInfo as wr, GitAuth as wt, AccessPolicyRule as x, SandboxClientConfig as xn, SnapshotResult as xr, FleetPromptDispatchResult as xt, buildSandboxMcpConfig as y, SSHCommandDescriptor as yn, SnapshotInfo as yr, FleetMachineId as yt, CodeExecutionResult as z, SandboxFleetManifestMachine as zn, WaitForOptions as zr, ListSandboxFleetOptions as zt };