@stateset/sandbox-cli 1.0.6 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (431) hide show
  1. package/CHANGELOG.md +123 -0
  2. package/LICENSE +22 -0
  3. package/README.md +940 -6
  4. package/dist/client.d.ts +789 -10
  5. package/dist/client.d.ts.map +1 -1
  6. package/dist/client.js +694 -12
  7. package/dist/client.js.map +1 -1
  8. package/dist/commands/alias.d.ts +5 -0
  9. package/dist/commands/alias.d.ts.map +1 -0
  10. package/dist/commands/alias.js +131 -0
  11. package/dist/commands/alias.js.map +1 -0
  12. package/dist/commands/api-key.d.ts +3 -0
  13. package/dist/commands/api-key.d.ts.map +1 -0
  14. package/dist/commands/api-key.js +119 -0
  15. package/dist/commands/api-key.js.map +1 -0
  16. package/dist/commands/artifact.d.ts.map +1 -1
  17. package/dist/commands/artifact.js +105 -46
  18. package/dist/commands/artifact.js.map +1 -1
  19. package/dist/commands/audit.d.ts +3 -0
  20. package/dist/commands/audit.d.ts.map +1 -0
  21. package/dist/commands/audit.js +191 -0
  22. package/dist/commands/audit.js.map +1 -0
  23. package/dist/commands/auth.d.ts +3 -0
  24. package/dist/commands/auth.d.ts.map +1 -0
  25. package/dist/commands/auth.js +126 -0
  26. package/dist/commands/auth.js.map +1 -0
  27. package/dist/commands/benchmark.d.ts +3 -0
  28. package/dist/commands/benchmark.d.ts.map +1 -0
  29. package/dist/commands/benchmark.js +166 -0
  30. package/dist/commands/benchmark.js.map +1 -0
  31. package/dist/commands/billing.d.ts +3 -0
  32. package/dist/commands/billing.d.ts.map +1 -0
  33. package/dist/commands/billing.js +139 -0
  34. package/dist/commands/billing.js.map +1 -0
  35. package/dist/commands/checkpoint.d.ts.map +1 -1
  36. package/dist/commands/checkpoint.js +105 -48
  37. package/dist/commands/checkpoint.js.map +1 -1
  38. package/dist/commands/completion.d.ts +3 -0
  39. package/dist/commands/completion.d.ts.map +1 -0
  40. package/dist/commands/completion.js +134 -0
  41. package/dist/commands/completion.js.map +1 -0
  42. package/dist/commands/computer-use.d.ts +3 -0
  43. package/dist/commands/computer-use.d.ts.map +1 -0
  44. package/dist/commands/computer-use.js +124 -0
  45. package/dist/commands/computer-use.js.map +1 -0
  46. package/dist/commands/config.d.ts.map +1 -1
  47. package/dist/commands/config.js +2 -1
  48. package/dist/commands/config.js.map +1 -1
  49. package/dist/commands/context.d.ts +3 -0
  50. package/dist/commands/context.d.ts.map +1 -0
  51. package/dist/commands/context.js +98 -0
  52. package/dist/commands/context.js.map +1 -0
  53. package/dist/commands/cp.d.ts +3 -0
  54. package/dist/commands/cp.d.ts.map +1 -0
  55. package/dist/commands/cp.js +165 -0
  56. package/dist/commands/cp.js.map +1 -0
  57. package/dist/commands/deploy.d.ts +3 -0
  58. package/dist/commands/deploy.d.ts.map +1 -1
  59. package/dist/commands/deploy.js +68 -20
  60. package/dist/commands/deploy.js.map +1 -1
  61. package/dist/commands/diff.d.ts +3 -0
  62. package/dist/commands/diff.d.ts.map +1 -0
  63. package/dist/commands/diff.js +186 -0
  64. package/dist/commands/diff.js.map +1 -0
  65. package/dist/commands/doctor.d.ts +30 -0
  66. package/dist/commands/doctor.d.ts.map +1 -1
  67. package/dist/commands/doctor.js +177 -207
  68. package/dist/commands/doctor.js.map +1 -1
  69. package/dist/commands/egress.d.ts +3 -0
  70. package/dist/commands/egress.d.ts.map +1 -0
  71. package/dist/commands/egress.js +155 -0
  72. package/dist/commands/egress.js.map +1 -0
  73. package/dist/commands/env.d.ts +3 -0
  74. package/dist/commands/env.d.ts.map +1 -0
  75. package/dist/commands/env.js +169 -0
  76. package/dist/commands/env.js.map +1 -0
  77. package/dist/commands/governance.d.ts +47 -0
  78. package/dist/commands/governance.d.ts.map +1 -0
  79. package/dist/commands/governance.js +345 -0
  80. package/dist/commands/governance.js.map +1 -0
  81. package/dist/commands/grade.d.ts +41 -0
  82. package/dist/commands/grade.d.ts.map +1 -1
  83. package/dist/commands/grade.js +255 -160
  84. package/dist/commands/grade.js.map +1 -1
  85. package/dist/commands/history.d.ts +4 -0
  86. package/dist/commands/history.d.ts.map +1 -0
  87. package/dist/commands/history.js +157 -0
  88. package/dist/commands/history.js.map +1 -0
  89. package/dist/commands/images.d.ts +8 -0
  90. package/dist/commands/images.d.ts.map +1 -0
  91. package/dist/commands/images.js +145 -0
  92. package/dist/commands/images.js.map +1 -0
  93. package/dist/commands/info.d.ts +3 -0
  94. package/dist/commands/info.d.ts.map +1 -0
  95. package/dist/commands/info.js +86 -0
  96. package/dist/commands/info.js.map +1 -0
  97. package/dist/commands/init.d.ts +3 -0
  98. package/dist/commands/init.d.ts.map +1 -0
  99. package/dist/commands/init.js +185 -0
  100. package/dist/commands/init.js.map +1 -0
  101. package/dist/commands/logs.d.ts +3 -0
  102. package/dist/commands/logs.d.ts.map +1 -0
  103. package/dist/commands/logs.js +129 -0
  104. package/dist/commands/logs.js.map +1 -0
  105. package/dist/commands/mcp.d.ts +3 -0
  106. package/dist/commands/mcp.d.ts.map +1 -0
  107. package/dist/commands/mcp.js +141 -0
  108. package/dist/commands/mcp.js.map +1 -0
  109. package/dist/commands/open.d.ts +3 -0
  110. package/dist/commands/open.d.ts.map +1 -0
  111. package/dist/commands/open.js +96 -0
  112. package/dist/commands/open.js.map +1 -0
  113. package/dist/commands/platform-status.d.ts +25 -5
  114. package/dist/commands/platform-status.d.ts.map +1 -1
  115. package/dist/commands/platform-status.js +199 -149
  116. package/dist/commands/platform-status.js.map +1 -1
  117. package/dist/commands/plugin.d.ts +5 -0
  118. package/dist/commands/plugin.d.ts.map +1 -0
  119. package/dist/commands/plugin.js +126 -0
  120. package/dist/commands/plugin.js.map +1 -0
  121. package/dist/commands/pool.d.ts.map +1 -1
  122. package/dist/commands/pool.js +52 -66
  123. package/dist/commands/pool.js.map +1 -1
  124. package/dist/commands/profile.d.ts +3 -0
  125. package/dist/commands/profile.d.ts.map +1 -0
  126. package/dist/commands/profile.js +107 -0
  127. package/dist/commands/profile.js.map +1 -0
  128. package/dist/commands/repl.d.ts +3 -0
  129. package/dist/commands/repl.d.ts.map +1 -0
  130. package/dist/commands/repl.js +390 -0
  131. package/dist/commands/repl.js.map +1 -0
  132. package/dist/commands/run.d.ts +3 -0
  133. package/dist/commands/run.d.ts.map +1 -0
  134. package/dist/commands/run.js +154 -0
  135. package/dist/commands/run.js.map +1 -0
  136. package/dist/commands/sandbox-processes.d.ts +27 -0
  137. package/dist/commands/sandbox-processes.d.ts.map +1 -0
  138. package/dist/commands/sandbox-processes.js +195 -0
  139. package/dist/commands/sandbox-processes.js.map +1 -0
  140. package/dist/commands/sandbox.d.ts.map +1 -1
  141. package/dist/commands/sandbox.js +562 -108
  142. package/dist/commands/sandbox.js.map +1 -1
  143. package/dist/commands/secret.d.ts +3 -0
  144. package/dist/commands/secret.d.ts.map +1 -0
  145. package/dist/commands/secret.js +128 -0
  146. package/dist/commands/secret.js.map +1 -0
  147. package/dist/commands/session.d.ts.map +1 -1
  148. package/dist/commands/session.js +285 -52
  149. package/dist/commands/session.js.map +1 -1
  150. package/dist/commands/snapshot.d.ts +3 -0
  151. package/dist/commands/snapshot.d.ts.map +1 -0
  152. package/dist/commands/snapshot.js +253 -0
  153. package/dist/commands/snapshot.js.map +1 -0
  154. package/dist/commands/ssh.d.ts +5 -0
  155. package/dist/commands/ssh.d.ts.map +1 -0
  156. package/dist/commands/ssh.js +154 -0
  157. package/dist/commands/ssh.js.map +1 -0
  158. package/dist/commands/swarm.d.ts +12 -0
  159. package/dist/commands/swarm.d.ts.map +1 -0
  160. package/dist/commands/swarm.js +288 -0
  161. package/dist/commands/swarm.js.map +1 -0
  162. package/dist/commands/template.d.ts +3 -0
  163. package/dist/commands/template.d.ts.map +1 -0
  164. package/dist/commands/template.js +102 -0
  165. package/dist/commands/template.js.map +1 -0
  166. package/dist/commands/terminal.d.ts +55 -0
  167. package/dist/commands/terminal.d.ts.map +1 -0
  168. package/dist/commands/terminal.js +438 -0
  169. package/dist/commands/terminal.js.map +1 -0
  170. package/dist/commands/top.d.ts +3 -0
  171. package/dist/commands/top.d.ts.map +1 -0
  172. package/dist/commands/top.js +116 -0
  173. package/dist/commands/top.js.map +1 -0
  174. package/dist/commands/tunnel.d.ts.map +1 -1
  175. package/dist/commands/tunnel.js +73 -26
  176. package/dist/commands/tunnel.js.map +1 -1
  177. package/dist/commands/update.d.ts +3 -0
  178. package/dist/commands/update.d.ts.map +1 -0
  179. package/dist/commands/update.js +51 -0
  180. package/dist/commands/update.js.map +1 -0
  181. package/dist/commands/wait.d.ts +3 -0
  182. package/dist/commands/wait.d.ts.map +1 -0
  183. package/dist/commands/wait.js +64 -0
  184. package/dist/commands/wait.js.map +1 -0
  185. package/dist/commands/webhook.d.ts +3 -0
  186. package/dist/commands/webhook.d.ts.map +1 -0
  187. package/dist/commands/webhook.js +169 -0
  188. package/dist/commands/webhook.js.map +1 -0
  189. package/dist/commands/workbench.d.ts +138 -0
  190. package/dist/commands/workbench.d.ts.map +1 -0
  191. package/dist/commands/workbench.js +531 -0
  192. package/dist/commands/workbench.js.map +1 -0
  193. package/dist/config.d.ts +14 -6
  194. package/dist/config.d.ts.map +1 -1
  195. package/dist/config.js +109 -16
  196. package/dist/config.js.map +1 -1
  197. package/dist/index.js +169 -11
  198. package/dist/index.js.map +1 -1
  199. package/dist/sandboxctl.d.ts +3 -0
  200. package/dist/sandboxctl.d.ts.map +1 -0
  201. package/dist/sandboxctl.js +37 -0
  202. package/dist/sandboxctl.js.map +1 -0
  203. package/dist/utils/context.d.ts +23 -0
  204. package/dist/utils/context.d.ts.map +1 -0
  205. package/dist/utils/context.js +48 -0
  206. package/dist/utils/context.js.map +1 -0
  207. package/dist/utils/credentials.d.ts +8 -0
  208. package/dist/utils/credentials.d.ts.map +1 -0
  209. package/dist/utils/credentials.js +120 -0
  210. package/dist/utils/credentials.js.map +1 -0
  211. package/dist/utils/dry-run.d.ts +4 -0
  212. package/dist/utils/dry-run.d.ts.map +1 -0
  213. package/dist/utils/dry-run.js +24 -0
  214. package/dist/utils/dry-run.js.map +1 -0
  215. package/dist/utils/egress-policy.d.ts +31 -0
  216. package/dist/utils/egress-policy.d.ts.map +1 -0
  217. package/dist/utils/egress-policy.js +83 -0
  218. package/dist/utils/egress-policy.js.map +1 -0
  219. package/dist/utils/errors.d.ts +53 -0
  220. package/dist/utils/errors.d.ts.map +1 -0
  221. package/dist/utils/errors.js +278 -0
  222. package/dist/utils/errors.js.map +1 -0
  223. package/dist/utils/file-content.d.ts +10 -0
  224. package/dist/utils/file-content.d.ts.map +1 -0
  225. package/dist/utils/file-content.js +14 -0
  226. package/dist/utils/file-content.js.map +1 -0
  227. package/dist/utils/grade-target.d.ts +12 -0
  228. package/dist/utils/grade-target.d.ts.map +1 -0
  229. package/dist/utils/grade-target.js +106 -0
  230. package/dist/utils/grade-target.js.map +1 -0
  231. package/dist/utils/health-report.d.ts +18 -0
  232. package/dist/utils/health-report.d.ts.map +1 -0
  233. package/dist/utils/health-report.js +43 -0
  234. package/dist/utils/health-report.js.map +1 -0
  235. package/dist/utils/output.d.ts +20 -0
  236. package/dist/utils/output.d.ts.map +1 -0
  237. package/dist/utils/output.js +123 -0
  238. package/dist/utils/output.js.map +1 -0
  239. package/dist/utils/plugins.d.ts +17 -0
  240. package/dist/utils/plugins.d.ts.map +1 -0
  241. package/dist/utils/plugins.js +57 -0
  242. package/dist/utils/plugins.js.map +1 -0
  243. package/dist/utils/resource-class.d.ts +12 -0
  244. package/dist/utils/resource-class.d.ts.map +1 -0
  245. package/dist/utils/resource-class.js +17 -0
  246. package/dist/utils/resource-class.js.map +1 -0
  247. package/dist/utils/shutdown.d.ts +14 -0
  248. package/dist/utils/shutdown.d.ts.map +1 -0
  249. package/dist/utils/shutdown.js +54 -0
  250. package/dist/utils/shutdown.js.map +1 -0
  251. package/dist/utils/swarm-plan.d.ts +69 -0
  252. package/dist/utils/swarm-plan.d.ts.map +1 -0
  253. package/dist/utils/swarm-plan.js +321 -0
  254. package/dist/utils/swarm-plan.js.map +1 -0
  255. package/dist/utils/template-create.d.ts +36 -0
  256. package/dist/utils/template-create.d.ts.map +1 -0
  257. package/dist/utils/template-create.js +116 -0
  258. package/dist/utils/template-create.js.map +1 -0
  259. package/dist/utils/tty.d.ts +44 -0
  260. package/dist/utils/tty.d.ts.map +1 -0
  261. package/dist/utils/tty.js +93 -0
  262. package/dist/utils/tty.js.map +1 -0
  263. package/dist/utils/warnings.d.ts +4 -0
  264. package/dist/utils/warnings.d.ts.map +1 -0
  265. package/dist/utils/warnings.js +22 -0
  266. package/dist/utils/warnings.js.map +1 -0
  267. package/dist/utils/watch.d.ts +7 -0
  268. package/dist/utils/watch.d.ts.map +1 -0
  269. package/dist/utils/watch.js +55 -0
  270. package/dist/utils/watch.js.map +1 -0
  271. package/dist/workbench/actions.d.ts +26 -0
  272. package/dist/workbench/actions.d.ts.map +1 -0
  273. package/dist/workbench/actions.js +39 -0
  274. package/dist/workbench/actions.js.map +1 -0
  275. package/dist/workbench/agent-chat.d.ts +71 -0
  276. package/dist/workbench/agent-chat.d.ts.map +1 -0
  277. package/dist/workbench/agent-chat.js +223 -0
  278. package/dist/workbench/agent-chat.js.map +1 -0
  279. package/dist/workbench/agents.d.ts +96 -0
  280. package/dist/workbench/agents.d.ts.map +1 -0
  281. package/dist/workbench/agents.js +370 -0
  282. package/dist/workbench/agents.js.map +1 -0
  283. package/dist/workbench/batch-uploads.d.ts +36 -0
  284. package/dist/workbench/batch-uploads.d.ts.map +1 -0
  285. package/dist/workbench/batch-uploads.js +154 -0
  286. package/dist/workbench/batch-uploads.js.map +1 -0
  287. package/dist/workbench/commands.d.ts +6 -0
  288. package/dist/workbench/commands.d.ts.map +1 -0
  289. package/dist/workbench/commands.js +517 -0
  290. package/dist/workbench/commands.js.map +1 -0
  291. package/dist/workbench/connection-failure.d.ts +9 -0
  292. package/dist/workbench/connection-failure.d.ts.map +1 -0
  293. package/dist/workbench/connection-failure.js +27 -0
  294. package/dist/workbench/connection-failure.js.map +1 -0
  295. package/dist/workbench/connection.d.ts +4 -0
  296. package/dist/workbench/connection.d.ts.map +1 -0
  297. package/dist/workbench/connection.js +28 -0
  298. package/dist/workbench/connection.js.map +1 -0
  299. package/dist/workbench/creation.d.ts +22 -0
  300. package/dist/workbench/creation.d.ts.map +1 -0
  301. package/dist/workbench/creation.js +102 -0
  302. package/dist/workbench/creation.js.map +1 -0
  303. package/dist/workbench/credits.d.ts +11 -0
  304. package/dist/workbench/credits.d.ts.map +1 -0
  305. package/dist/workbench/credits.js +132 -0
  306. package/dist/workbench/credits.js.map +1 -0
  307. package/dist/workbench/docker.d.ts +18 -0
  308. package/dist/workbench/docker.d.ts.map +1 -0
  309. package/dist/workbench/docker.js +207 -0
  310. package/dist/workbench/docker.js.map +1 -0
  311. package/dist/workbench/execution.d.ts +14 -0
  312. package/dist/workbench/execution.d.ts.map +1 -0
  313. package/dist/workbench/execution.js +24 -0
  314. package/dist/workbench/execution.js.map +1 -0
  315. package/dist/workbench/files.d.ts +51 -0
  316. package/dist/workbench/files.d.ts.map +1 -0
  317. package/dist/workbench/files.js +80 -0
  318. package/dist/workbench/files.js.map +1 -0
  319. package/dist/workbench/history.d.ts +34 -0
  320. package/dist/workbench/history.d.ts.map +1 -0
  321. package/dist/workbench/history.js +50 -0
  322. package/dist/workbench/history.js.map +1 -0
  323. package/dist/workbench/input-batch-commands.d.ts +6 -0
  324. package/dist/workbench/input-batch-commands.d.ts.map +1 -0
  325. package/dist/workbench/input-batch-commands.js +41 -0
  326. package/dist/workbench/input-batch-commands.js.map +1 -0
  327. package/dist/workbench/kitty-diacritics.d.ts +2 -0
  328. package/dist/workbench/kitty-diacritics.d.ts.map +1 -0
  329. package/dist/workbench/kitty-diacritics.js +22 -0
  330. package/dist/workbench/kitty-diacritics.js.map +1 -0
  331. package/dist/workbench/kitty-graphics.d.ts +59 -0
  332. package/dist/workbench/kitty-graphics.d.ts.map +1 -0
  333. package/dist/workbench/kitty-graphics.js +263 -0
  334. package/dist/workbench/kitty-graphics.js.map +1 -0
  335. package/dist/workbench/live-execution.d.ts +51 -0
  336. package/dist/workbench/live-execution.d.ts.map +1 -0
  337. package/dist/workbench/live-execution.js +222 -0
  338. package/dist/workbench/live-execution.js.map +1 -0
  339. package/dist/workbench/model.d.ts +110 -0
  340. package/dist/workbench/model.d.ts.map +1 -0
  341. package/dist/workbench/model.js +249 -0
  342. package/dist/workbench/model.js.map +1 -0
  343. package/dist/workbench/overview.d.ts +11 -0
  344. package/dist/workbench/overview.d.ts.map +1 -0
  345. package/dist/workbench/overview.js +92 -0
  346. package/dist/workbench/overview.js.map +1 -0
  347. package/dist/workbench/png.d.ts +10 -0
  348. package/dist/workbench/png.d.ts.map +1 -0
  349. package/dist/workbench/png.js +51 -0
  350. package/dist/workbench/png.js.map +1 -0
  351. package/dist/workbench/python-task.d.ts +21 -0
  352. package/dist/workbench/python-task.d.ts.map +1 -0
  353. package/dist/workbench/python-task.js +52 -0
  354. package/dist/workbench/python-task.js.map +1 -0
  355. package/dist/workbench/registry-commands.d.ts +8 -0
  356. package/dist/workbench/registry-commands.d.ts.map +1 -0
  357. package/dist/workbench/registry-commands.js +93 -0
  358. package/dist/workbench/registry-commands.js.map +1 -0
  359. package/dist/workbench/registry.d.ts +76 -0
  360. package/dist/workbench/registry.d.ts.map +1 -0
  361. package/dist/workbench/registry.js +353 -0
  362. package/dist/workbench/registry.js.map +1 -0
  363. package/dist/workbench/renderer.d.ts +6 -0
  364. package/dist/workbench/renderer.d.ts.map +1 -0
  365. package/dist/workbench/renderer.js +18 -0
  366. package/dist/workbench/renderer.js.map +1 -0
  367. package/dist/workbench/results.d.ts +15 -0
  368. package/dist/workbench/results.d.ts.map +1 -0
  369. package/dist/workbench/results.js +29 -0
  370. package/dist/workbench/results.js.map +1 -0
  371. package/dist/workbench/task-archive.d.ts +23 -0
  372. package/dist/workbench/task-archive.d.ts.map +1 -0
  373. package/dist/workbench/task-archive.js +56 -0
  374. package/dist/workbench/task-archive.js.map +1 -0
  375. package/dist/workbench/task-board.d.ts +26 -0
  376. package/dist/workbench/task-board.d.ts.map +1 -0
  377. package/dist/workbench/task-board.js +43 -0
  378. package/dist/workbench/task-board.js.map +1 -0
  379. package/dist/workbench/task-monitor.d.ts +35 -0
  380. package/dist/workbench/task-monitor.d.ts.map +1 -0
  381. package/dist/workbench/task-monitor.js +176 -0
  382. package/dist/workbench/task-monitor.js.map +1 -0
  383. package/dist/workbench/tasks.d.ts +93 -0
  384. package/dist/workbench/tasks.d.ts.map +1 -0
  385. package/dist/workbench/tasks.js +195 -0
  386. package/dist/workbench/tasks.js.map +1 -0
  387. package/dist/workbench/terminal.d.ts +82 -0
  388. package/dist/workbench/terminal.d.ts.map +1 -0
  389. package/dist/workbench/terminal.js +2607 -0
  390. package/dist/workbench/terminal.js.map +1 -0
  391. package/dist/workbench/text.d.ts +10 -0
  392. package/dist/workbench/text.d.ts.map +1 -0
  393. package/dist/workbench/text.js +72 -0
  394. package/dist/workbench/text.js.map +1 -0
  395. package/dist/workbench/uploads.d.ts +12 -0
  396. package/dist/workbench/uploads.d.ts.map +1 -0
  397. package/dist/workbench/uploads.js +16 -0
  398. package/dist/workbench/uploads.js.map +1 -0
  399. package/dist/workbench/worker-launch.d.ts +10 -0
  400. package/dist/workbench/worker-launch.d.ts.map +1 -0
  401. package/dist/workbench/worker-launch.js +30 -0
  402. package/dist/workbench/worker-launch.js.map +1 -0
  403. package/dist/workbench/worker-monitor.d.ts +33 -0
  404. package/dist/workbench/worker-monitor.d.ts.map +1 -0
  405. package/dist/workbench/worker-monitor.js +142 -0
  406. package/dist/workbench/worker-monitor.js.map +1 -0
  407. package/dist/workbench/worker-output.d.ts +8 -0
  408. package/dist/workbench/worker-output.d.ts.map +1 -0
  409. package/dist/workbench/worker-output.js +32 -0
  410. package/dist/workbench/worker-output.js.map +1 -0
  411. package/dist/workbench/worker-result.d.ts +29 -0
  412. package/dist/workbench/worker-result.d.ts.map +1 -0
  413. package/dist/workbench/worker-result.js +85 -0
  414. package/dist/workbench/worker-result.js.map +1 -0
  415. package/dist/workbench/workers.d.ts +49 -0
  416. package/dist/workbench/workers.d.ts.map +1 -0
  417. package/dist/workbench/workers.js +53 -0
  418. package/dist/workbench/workers.js.map +1 -0
  419. package/package.json +38 -17
  420. package/dist/__tests__/client.test.d.ts +0 -2
  421. package/dist/__tests__/client.test.d.ts.map +0 -1
  422. package/dist/__tests__/client.test.js +0 -198
  423. package/dist/__tests__/client.test.js.map +0 -1
  424. package/dist/__tests__/config.test.d.ts +0 -2
  425. package/dist/__tests__/config.test.d.ts.map +0 -1
  426. package/dist/__tests__/config.test.js +0 -74
  427. package/dist/__tests__/config.test.js.map +0 -1
  428. package/dist/__tests__/utils-cli.test.d.ts +0 -2
  429. package/dist/__tests__/utils-cli.test.d.ts.map +0 -1
  430. package/dist/__tests__/utils-cli.test.js +0 -35
  431. package/dist/__tests__/utils-cli.test.js.map +0 -1
@@ -4,7 +4,47 @@ import ora from 'ora';
4
4
  import { table } from 'table';
5
5
  import { getClient } from '../client.js';
6
6
  import { getConfig } from '../config.js';
7
- import { formatCliError, parseIntOption, formatDateTime, } from '../utils/cli.js';
7
+ import { parseIntOption, formatDateTime, } from '../utils/cli.js';
8
+ import { withRetry, handleCommandError } from '../utils/errors.js';
9
+ import { resolveFormat, formatOutput } from '../utils/output.js';
10
+ import { dryRunGuard } from '../utils/dry-run.js';
11
+ import { printCheckpointWarnings } from '../utils/warnings.js';
12
+ import { watchLoop } from '../utils/watch.js';
13
+ import { registerProcessCommands } from './sandbox-processes.js';
14
+ import { governanceCreateFields, registerSandboxEgressCommand, registerTimelineCommand } from './governance.js';
15
+ import { resourceClassCreateField } from '../utils/resource-class.js';
16
+ import { confirmedCommandExitCode } from '../workbench/execution.js';
17
+ import { fileReadBytes } from '../utils/file-content.js';
18
+ import { createSandbox, printSetupFailure, setupProgressText, setupWaitMs } from '../utils/template-create.js';
19
+ const sandboxRecovery = 'Inspect with `stateset sandbox get <sandbox-id>` before repeating.';
20
+ const branchRecovery = 'Inspect `stateset sandbox list` and the source sandbox before repeating; a new sandbox may already exist.';
21
+ const workspaceRecovery = 'Inspect workspace files with `stateset sandbox list-files <sandbox-id>` before repeating.';
22
+ function toSandboxView(value) {
23
+ const sandbox = value;
24
+ return {
25
+ id: sandbox.id ?? sandbox.sandbox_id ?? '',
26
+ sessionId: sandbox.sessionId ?? sandbox.session_id ?? '',
27
+ status: sandbox.status ?? 'unknown',
28
+ createdAt: sandbox.createdAt ?? sandbox.created_at ?? '',
29
+ expiresAt: sandbox.expiresAt ?? sandbox.expires_at ?? '',
30
+ podIp: sandbox.podIp ?? sandbox.pod_ip,
31
+ maxExpiresAt: sandbox.maxExpiresAt ?? sandbox.max_expires_at,
32
+ maxLifetimeSeconds: sandbox.maxLifetimeSeconds ?? sandbox.max_lifetime_seconds,
33
+ remainingExtendSeconds: sandbox.remainingExtendSeconds ?? sandbox.remaining_extend_seconds,
34
+ lifetimeUsedSeconds: sandbox.lifetimeUsedSeconds ?? sandbox.lifetime_used_seconds,
35
+ lifetimeUsedPercent: sandbox.lifetimeUsedPercent ?? sandbox.lifetime_used_percent,
36
+ requestedAdditionalSeconds: sandbox.requestedAdditionalSeconds ?? sandbox.requested_additional_seconds,
37
+ appliedAdditionalSeconds: sandbox.appliedAdditionalSeconds ?? sandbox.applied_additional_seconds,
38
+ additionalSeconds: sandbox.additionalSeconds ?? sandbox.additional_seconds,
39
+ };
40
+ }
41
+ const SANDBOX_COLUMNS = [
42
+ { key: 'id', header: 'ID', transform: (v) => String(v ?? '').substring(0, 20) },
43
+ { key: 'status', header: 'Status' },
44
+ { key: 'createdAt', header: 'Created', transform: (v) => formatDateTime(v) },
45
+ { key: 'expiresAt', header: 'Expires', transform: (v) => formatDateTime(v) },
46
+ { key: 'sessionId', header: 'Session', transform: (v) => String(v ?? '').substring(0, 12) },
47
+ ];
8
48
  export const sandboxCommand = new Command('sandbox')
9
49
  .description('Manage sandbox environments');
10
50
  // Create sandbox
@@ -12,15 +52,58 @@ sandboxCommand
12
52
  .command('create')
13
53
  .description('Create a new sandbox')
14
54
  .option('-t, --timeout <seconds>', 'Sandbox timeout in seconds')
55
+ .option('--startup-timeout <seconds>', 'Client wait for sandbox creation (1-600 seconds); a template with setup gets 300 more unless this is set', '210')
56
+ .option('--template <id>', 'Built-in template id (see `stateset template list`); supplies the image and the defaults for CPUs, memory, timeout and env, and its files and setup commands if it has any')
15
57
  .option('-c, --cpus <cpus>', 'CPU limit (e.g., "0.5", "1")')
16
58
  .option('-m, --memory <memory>', 'Memory limit (e.g., "512Mi", "1Gi")')
17
- .option('-i, --isolation <isolation>', 'Isolation level (container, gvisor, microvm)')
59
+ .option('-i, --isolation <isolation>', 'Isolation level (container, gvisor, microvm, kata)')
60
+ .option('--desktop-os <os>', 'Desktop OS (linux, windows, macos)', 'linux')
61
+ .option('--resource-class <class>', 'Resource class: shared (burstable, preemptible Spot capacity, 4 vCPU / 8 GB = $0.028/h) or dedicated (guaranteed). Default: the deployment default')
62
+ .option('--durable', 'Create a durable sandbox that is recovered after pod/node loss')
18
63
  .option('-e, --env <env...>', 'Environment variables (KEY=VALUE)')
19
- .action(async (options) => {
64
+ .option('--egress-allow <rules...>', 'Only allow egress to these hosts / *.domains / IPs / CIDRs (narrows the org policy)')
65
+ .option('--egress-deny <rules...>', 'Deny egress to these hosts / *.domains / IPs / CIDRs')
66
+ .option('--credential <spec...>', 'Egress gateway credential: host=<host>,secret=<SECRET_NAME>[,header=..][,format=..][,path_prefix=..] (secret scope egress)')
67
+ .option('--max-cost-cents <cents>', 'Run budget: stop at this cost (compute + LLM)')
68
+ .option('--max-llm-tokens <n>', 'Run budget: LLM gateway tokens (input + output)')
69
+ .option('--max-runtime <seconds>', 'Run budget: billable runtime')
70
+ .option('--on-exhausted <action>', 'When the budget is spent: stop (default), pause, notify')
71
+ .option('--json', 'Output as JSON')
72
+ .action(async (options, command) => {
73
+ const config = getConfig();
74
+ // A template has its own timeout, and the API lets a timeout the request
75
+ // names win over it: the profile default is sent only without a template.
76
+ const timeoutSeconds = options.template !== undefined && options.timeout === undefined
77
+ ? undefined
78
+ : parseIntOption(options.timeout, { label: 'timeout', min: 1, defaultValue: config.defaultTimeout });
79
+ const startupTimeoutMs = parseIntOption(options.startupTimeout, {
80
+ label: 'startup-timeout', min: 1, max: 600,
81
+ }) * 1000;
82
+ const startupTimeoutChosen = command.getOptionValueSource('startupTimeout') !== 'default';
83
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
84
+ let resourceClass;
85
+ try {
86
+ resourceClass = resourceClassCreateField(options.resourceClass);
87
+ }
88
+ catch (error) {
89
+ handleCommandError(error);
90
+ }
91
+ if (dryRunGuard(globalOpts, 'sandbox create', {
92
+ Template: options.template,
93
+ Timeout: timeoutSeconds === undefined ? 'template default' : `${timeoutSeconds}s`,
94
+ 'Startup wait': options.template !== undefined && !startupTimeoutChosen
95
+ ? `${startupTimeoutMs / 1000}s (${setupWaitMs(startupTimeoutMs, false) / 1000}s if the template has setup)`
96
+ : `${startupTimeoutMs / 1000}s`,
97
+ CPUs: options.cpus,
98
+ Memory: options.memory,
99
+ Isolation: options.isolation,
100
+ 'Resource class': resourceClass.resource_class,
101
+ 'Desktop OS': options.desktopOs,
102
+ Durable: options.durable ? 'yes' : undefined,
103
+ }))
104
+ return;
20
105
  const spinner = ora('Creating sandbox...').start();
21
106
  try {
22
- const config = getConfig();
23
- const timeoutSeconds = parseIntOption(options.timeout, { label: 'timeout', min: 1, defaultValue: config.defaultTimeout });
24
107
  const client = getClient();
25
108
  const env = {};
26
109
  if (options.env) {
@@ -29,26 +112,65 @@ sandboxCommand
29
112
  env[key] = valueParts.join('=');
30
113
  }
31
114
  }
32
- const result = await client.sandbox.create({
33
- timeout_seconds: timeoutSeconds,
34
- cpus: options.cpus,
35
- memory: options.memory,
36
- isolation: options.isolation,
37
- env: Object.keys(env).length > 0 ? env : undefined,
115
+ const { sandbox: result, setupWarnings } = await createSandbox(client, {
116
+ fields: {
117
+ timeout_seconds: timeoutSeconds,
118
+ template: options.template,
119
+ cpus: options.cpus,
120
+ memory: options.memory,
121
+ isolation: options.isolation,
122
+ desktop_os: options.desktopOs !== 'linux' ? options.desktopOs : undefined,
123
+ durable: options.durable ? true : undefined,
124
+ env: Object.keys(env).length > 0 ? env : undefined,
125
+ ...resourceClass,
126
+ ...governanceCreateFields(options),
127
+ },
128
+ startupTimeoutMs,
129
+ startupTimeoutChosen,
130
+ onSetup: (waitMs) => { spinner.text = setupProgressText(options.template, waitMs); },
38
131
  });
39
- spinner.succeed('Sandbox created');
132
+ const sandbox = toSandboxView(result);
133
+ // The API keeps a sandbox whose template setup failed; so does the CLI,
134
+ // but the create is not reported as a success.
135
+ const reportSetupFailure = () => {
136
+ if (setupWarnings.length === 0)
137
+ return;
138
+ printSetupFailure(setupWarnings, `Sandbox ${sandbox.id} was kept: it is running, and billed until it expires or `
139
+ + `is stopped (\`stateset sandbox stop ${sandbox.id}\`).`);
140
+ process.exitCode = 1;
141
+ };
142
+ const format = resolveFormat({ ...options, ...globalOpts });
143
+ if (format !== 'table') {
144
+ spinner.stop();
145
+ const { formatSingleOutput } = await import('../utils/output.js');
146
+ console.log(formatSingleOutput({
147
+ ...sandbox,
148
+ ...(options.template !== undefined ? { template: options.template } : {}),
149
+ ...(setupWarnings.length > 0 ? { warnings: setupWarnings } : {}),
150
+ }, { format }));
151
+ reportSetupFailure();
152
+ return;
153
+ }
154
+ if (setupWarnings.length > 0) {
155
+ spinner.warn(`Sandbox created, but the setup of template ${options.template} failed`);
156
+ }
157
+ else {
158
+ spinner.succeed('Sandbox created');
159
+ }
40
160
  console.log();
41
- console.log(chalk.green('Sandbox ID:'), result.sandbox_id);
42
- console.log(chalk.gray('Session ID:'), result.session_id);
43
- console.log(chalk.gray('Expires at:'), result.expires_at);
161
+ console.log(chalk.green('Sandbox ID:'), sandbox.id);
162
+ console.log(chalk.gray('Session ID:'), sandbox.sessionId);
163
+ if (options.template !== undefined) {
164
+ console.log(chalk.gray('Template:'), options.template);
165
+ }
166
+ console.log(chalk.gray('Expires at:'), sandbox.expiresAt);
44
167
  console.log();
45
168
  console.log(chalk.gray('Run commands with:'));
46
- console.log(chalk.cyan(` stateset sandbox exec ${result.sandbox_id} -- <command>`));
169
+ console.log(chalk.cyan(` stateset sandbox exec ${sandbox.id} -- <command>`));
170
+ reportSetupFailure();
47
171
  }
48
172
  catch (error) {
49
- spinner.fail('Failed to create sandbox');
50
- console.error(chalk.red(formatCliError(error)));
51
- process.exit(1);
173
+ handleCommandError(error, spinner);
52
174
  }
53
175
  });
54
176
  // List sandboxes
@@ -57,14 +179,17 @@ sandboxCommand
57
179
  .alias('ls')
58
180
  .description('List all sandboxes')
59
181
  .option('--json', 'Output as JSON')
182
+ .option('-w, --watch', 'Watch for changes')
183
+ .option('-i, --interval <seconds>', 'Watch interval in seconds', '5')
60
184
  .action(async (options) => {
61
- const spinner = ora('Fetching sandboxes...').start();
62
- try {
185
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
186
+ const format = resolveFormat({ ...options, ...globalOpts });
187
+ const renderList = async () => {
63
188
  const client = getClient();
64
- const result = await client.sandbox.list();
65
- spinner.stop();
66
- if (options.json) {
67
- console.log(JSON.stringify(result.sandboxes, null, 2));
189
+ const result = await withRetry(() => client.sandbox.list());
190
+ if (format !== 'table') {
191
+ const views = result.sandboxes.map(toSandboxView);
192
+ console.log(formatOutput(views, { format, columns: SANDBOX_COLUMNS, emptyMessage: 'No sandboxes found' }));
68
193
  return;
69
194
  }
70
195
  if (result.sandboxes.length === 0) {
@@ -73,21 +198,32 @@ sandboxCommand
73
198
  }
74
199
  const tableData = [
75
200
  ['ID', 'Status', 'Created', 'Expires', 'Extend Left', 'Session'].map(h => chalk.bold(h)),
76
- ...result.sandboxes.map((s) => [
77
- s.sandbox_id.substring(0, 20),
78
- colorStatus(s.status),
79
- formatDate(s.created_at),
80
- formatDate(s.expires_at),
81
- formatRemainingExtendBudget(s.remaining_extend_seconds),
82
- s.session_id.substring(0, 12),
83
- ]),
201
+ ...result.sandboxes.map((value) => {
202
+ const sandbox = toSandboxView(value);
203
+ return [
204
+ sandbox.id.substring(0, 20),
205
+ colorStatus(sandbox.status),
206
+ formatDate(sandbox.createdAt),
207
+ formatDate(sandbox.expiresAt),
208
+ formatRemainingExtendBudget(sandbox.remainingExtendSeconds),
209
+ sandbox.sessionId.substring(0, 12),
210
+ ];
211
+ }),
84
212
  ];
85
213
  console.log(table(tableData));
214
+ };
215
+ if (options.watch) {
216
+ const intervalMs = parseIntOption(options.interval, { label: 'interval', min: 1 }) * 1000;
217
+ await watchLoop(renderList, { intervalMs });
218
+ return;
219
+ }
220
+ const spinner = ora('Fetching sandboxes...').start();
221
+ try {
222
+ spinner.stop();
223
+ await renderList();
86
224
  }
87
225
  catch (error) {
88
- spinner.fail('Failed to list sandboxes');
89
- console.error(chalk.red(formatCliError(error)));
90
- process.exit(1);
226
+ handleCommandError(error, spinner);
91
227
  }
92
228
  });
93
229
  // Get sandbox details
@@ -99,43 +235,41 @@ sandboxCommand
99
235
  const spinner = ora('Fetching sandbox...').start();
100
236
  try {
101
237
  const client = getClient();
102
- const result = await client.sandbox.get(sandboxId);
238
+ const result = await withRetry(() => client.sandbox.get(sandboxId), { spinner });
239
+ const sandbox = toSandboxView(result);
103
240
  spinner.stop();
104
- if (options.json) {
105
- console.log(JSON.stringify(result, null, 2));
241
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
242
+ const format = resolveFormat({ ...options, ...globalOpts });
243
+ if (format !== 'table') {
244
+ const { formatSingleOutput } = await import('../utils/output.js');
245
+ console.log(formatSingleOutput(sandbox, { format }));
106
246
  return;
107
247
  }
108
248
  console.log(chalk.bold('Sandbox Details'));
109
- console.log(chalk.gray('─'.repeat(40)));
110
- console.log(`ID: ${result.sandbox_id}`);
111
- console.log(`Session: ${result.session_id}`);
112
- console.log(`Status: ${colorStatus(result.status)}`);
113
- if (result.pod_ip) {
114
- console.log(`Pod IP: ${result.pod_ip}`);
115
- }
116
- console.log(`Created: ${formatDateTime(result.created_at)}`);
117
- console.log(`Expires: ${formatDateTime(result.expires_at)}`);
118
- if (result.max_expires_at) {
119
- console.log(`Max Expires: ${formatDateTime(result.max_expires_at)}`);
120
- }
121
- if (typeof result.remaining_extend_seconds === 'number') {
122
- console.log(`Extend Left: ${formatRemainingExtendBudget(result.remaining_extend_seconds)}`);
123
- }
124
- const lifetimeMetadata = result;
125
- if (typeof lifetimeMetadata.lifetime_used_seconds === 'number'
126
- && typeof lifetimeMetadata.max_lifetime_seconds === 'number') {
127
- const usedPercent = typeof lifetimeMetadata.lifetime_used_percent === 'number'
128
- ? lifetimeMetadata.lifetime_used_percent
129
- : (lifetimeMetadata.max_lifetime_seconds > 0
130
- ? (lifetimeMetadata.lifetime_used_seconds / lifetimeMetadata.max_lifetime_seconds) * 100
249
+ console.log(chalk.gray('\u2500'.repeat(40)));
250
+ console.log(`ID: ${sandbox.id}`);
251
+ console.log(`Session: ${sandbox.sessionId}`);
252
+ console.log(`Status: ${colorStatus(sandbox.status)}`);
253
+ if (sandbox.podIp) {
254
+ console.log(`Pod IP: ${sandbox.podIp}`);
255
+ }
256
+ console.log(`Created: ${formatDateTime(sandbox.createdAt)}`);
257
+ console.log(`Expires: ${formatDateTime(sandbox.expiresAt)}`);
258
+ if (sandbox.maxExpiresAt) {
259
+ console.log(`Max Expires: ${formatDateTime(sandbox.maxExpiresAt)}`);
260
+ }
261
+ if (typeof sandbox.lifetimeUsedSeconds === 'number'
262
+ && typeof sandbox.maxLifetimeSeconds === 'number') {
263
+ const usedPercent = typeof sandbox.lifetimeUsedPercent === 'number'
264
+ ? sandbox.lifetimeUsedPercent
265
+ : (sandbox.maxLifetimeSeconds > 0
266
+ ? (sandbox.lifetimeUsedSeconds / sandbox.maxLifetimeSeconds) * 100
131
267
  : 0);
132
- console.log(`Lifetime: ${formatBudgetDuration(lifetimeMetadata.lifetime_used_seconds)} / ${formatBudgetDuration(lifetimeMetadata.max_lifetime_seconds)} (${usedPercent.toFixed(2)}%)`);
268
+ console.log(`Lifetime: ${formatBudgetDuration(sandbox.lifetimeUsedSeconds)} / ${formatBudgetDuration(sandbox.maxLifetimeSeconds)} (${usedPercent.toFixed(2)}%)`);
133
269
  }
134
270
  }
135
271
  catch (error) {
136
- spinner.fail('Failed to get sandbox');
137
- console.error(chalk.red(formatCliError(error)));
138
- process.exit(1);
272
+ handleCommandError(error, spinner);
139
273
  }
140
274
  });
141
275
  // Execute command in sandbox
@@ -148,10 +282,17 @@ sandboxCommand
148
282
  const spinner = ora('Executing command...').start();
149
283
  try {
150
284
  const client = getClient();
285
+ // The SDK retries only provably unsent calls. An outer generic retry
286
+ // would replay a command after a lost response or ambiguous server error.
151
287
  const result = await client.sandbox.execute(sandboxId, command);
152
288
  spinner.stop();
153
- if (options.json) {
154
- console.log(JSON.stringify(result, null, 2));
289
+ const exitCode = confirmedCommandExitCode(result);
290
+ process.exitCode = exitCode ?? 1;
291
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
292
+ const format = resolveFormat({ ...options, ...globalOpts });
293
+ if (format !== 'table') {
294
+ const { formatSingleOutput } = await import('../utils/output.js');
295
+ console.log(formatSingleOutput(result, { format }));
155
296
  return;
156
297
  }
157
298
  if (result.stdout) {
@@ -160,15 +301,15 @@ sandboxCommand
160
301
  if (result.stderr) {
161
302
  console.error(chalk.yellow(result.stderr));
162
303
  }
163
- if (result.exit_code !== 0) {
164
- console.log(chalk.red(`Exit code: ${result.exit_code}`));
165
- process.exit(result.exit_code);
304
+ if (exitCode === undefined) {
305
+ console.error(chalk.yellow('Outcome unknown. Inspect the execution before repeating; do not automatically retry.'));
306
+ }
307
+ else if (exitCode !== 0) {
308
+ console.log(chalk.red(`Exit code: ${exitCode}`));
166
309
  }
167
310
  }
168
311
  catch (error) {
169
- spinner.fail('Failed to execute command');
170
- console.error(chalk.red(formatCliError(error)));
171
- process.exit(1);
312
+ handleCommandError(error, spinner);
172
313
  }
173
314
  });
174
315
  // Stop sandbox
@@ -176,16 +317,166 @@ sandboxCommand
176
317
  .command('stop <sandbox-id>')
177
318
  .description('Stop a sandbox')
178
319
  .action(async (sandboxId) => {
320
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
321
+ if (dryRunGuard(globalOpts, 'sandbox stop', { 'Sandbox ID': sandboxId }))
322
+ return;
179
323
  const spinner = ora('Stopping sandbox...').start();
180
324
  try {
181
325
  const client = getClient();
182
- await client.sandbox.stop(sandboxId);
183
- spinner.succeed(`Sandbox ${sandboxId} stopped`);
326
+ // Let the SDK decide which transport attempts are safe. An outer retry
327
+ // can repeat a mutation after its response was lost.
328
+ const result = await client.sandbox.stop(sandboxId);
329
+ if (result?.success !== true)
330
+ throw new Error('Sandbox stop was not acknowledged.');
331
+ spinner.succeed(`Stop acknowledged for sandbox ${sandboxId}`);
332
+ }
333
+ catch (error) {
334
+ handleCommandError(error, spinner, { mutationRecovery: sandboxRecovery });
335
+ }
336
+ });
337
+ // Fork sandbox
338
+ sandboxCommand
339
+ .command('fork <sandbox-id>')
340
+ .description('Fork a sandbox into a new one from a checkpoint of its state')
341
+ .option('--no-env', 'Do not carry environment variables into the fork')
342
+ .option('--name <name>', 'Checkpoint name')
343
+ .action(async (sandboxId, options) => {
344
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
345
+ if (dryRunGuard(globalOpts, 'sandbox fork', { 'Sandbox ID': sandboxId }))
346
+ return;
347
+ const spinner = ora('Forking sandbox...').start();
348
+ try {
349
+ const client = getClient();
350
+ const result = await client.sandbox.fork(sandboxId, {
351
+ include_env: options.env !== false,
352
+ checkpoint_name: options.name,
353
+ });
354
+ spinner.succeed(`Sandbox forked: ${result.forked_id}`);
355
+ console.log(chalk.gray('Checkpoint:'), result.checkpoint_id);
356
+ printCheckpointWarnings(result.warnings);
357
+ }
358
+ catch (error) {
359
+ handleCommandError(error, spinner, { mutationRecovery: branchRecovery });
360
+ }
361
+ });
362
+ // Promote sandbox to another isolation tier
363
+ sandboxCommand
364
+ .command('promote <sandbox-id>')
365
+ .description('Promote a sandbox into a different isolation tier')
366
+ .requiredOption('--isolation <tier>', 'Target isolation (container, gvisor, microvm, kata, wasm)')
367
+ .option('--no-env', 'Do not carry environment variables into the promoted sandbox')
368
+ .option('--stop-source', 'Stop the source sandbox after promotion')
369
+ .action(async (sandboxId, options) => {
370
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
371
+ if (dryRunGuard(globalOpts, 'sandbox promote', { 'Sandbox ID': sandboxId, 'Isolation': options.isolation }))
372
+ return;
373
+ const spinner = ora('Promoting sandbox...').start();
374
+ try {
375
+ const client = getClient();
376
+ const result = await client.sandbox.promote(sandboxId, {
377
+ target_isolation: options.isolation,
378
+ include_env: options.env !== false,
379
+ stop_source: options.stopSource,
380
+ });
381
+ spinner.succeed(`Sandbox promoted: ${result.promoted_id}`);
382
+ console.log(chalk.gray('Checkpoint:'), result.checkpoint_id);
383
+ printCheckpointWarnings(result.warnings);
384
+ }
385
+ catch (error) {
386
+ handleCommandError(error, spinner, { mutationRecovery: branchRecovery });
387
+ }
388
+ });
389
+ // Pause a sandbox (snapshot mode: durable sandboxes; filesystem kept, memory and processes not)
390
+ sandboxCommand
391
+ .command('pause <sandbox-id>')
392
+ .description('Pause a durable sandbox: its pod is stopped, its workspace kept; billing stops until resumed')
393
+ .option('--no-wait', 'Return as soon as the pause has started (202 pausing)')
394
+ .option('--timeout <seconds>', 'Longest wait for the pause to finish (max 120)')
395
+ .option('--json', 'Output as JSON')
396
+ .action(async (sandboxId, options) => {
397
+ const timeoutSeconds = options.timeout !== undefined
398
+ ? parseIntOption(options.timeout, { label: 'timeout', min: 1, max: 120 })
399
+ : undefined;
400
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
401
+ if (dryRunGuard(globalOpts, 'sandbox pause', {
402
+ 'Sandbox ID': sandboxId,
403
+ 'Wait': options.wait !== false ? 'yes' : 'no',
404
+ }))
405
+ return;
406
+ const spinner = ora('Pausing sandbox...').start();
407
+ try {
408
+ const client = getClient();
409
+ const result = await client.sandbox.pause(sandboxId, { wait: options.wait !== false, timeoutSeconds });
410
+ if (result?.sandbox_id !== sandboxId || !['paused', 'pausing'].includes(result.status)) {
411
+ throw new Error('Sandbox pause was not confirmed for the requested sandbox.');
412
+ }
413
+ spinner.stop();
414
+ const format = resolveFormat({ ...options, ...globalOpts });
415
+ if (format !== 'table') {
416
+ const { formatSingleOutput } = await import('../utils/output.js');
417
+ console.log(formatSingleOutput(result, { format }));
418
+ return;
419
+ }
420
+ if (result.status === 'pausing') {
421
+ console.log(chalk.yellow(`Sandbox ${sandboxId} is pausing`));
422
+ console.log(chalk.gray('Check with:'), `stateset sandbox get ${sandboxId}`);
423
+ return;
424
+ }
425
+ console.log(chalk.green(`Sandbox ${sandboxId} paused`));
426
+ if (result.paused_at)
427
+ console.log(chalk.gray('Paused at:'), result.paused_at);
428
+ if (typeof result.remaining_timeout_seconds === 'number') {
429
+ console.log(chalk.gray('Lifetime left on resume:'), formatDuration(result.remaining_timeout_seconds));
430
+ }
431
+ if (result.paused_expires_at)
432
+ console.log(chalk.gray('Stopped if still paused at:'), result.paused_expires_at);
433
+ console.log(chalk.gray('Kept: workspace filesystem. Not kept: memory, running processes.'));
434
+ }
435
+ catch (error) {
436
+ handleCommandError(error, spinner, { mutationRecovery: sandboxRecovery });
437
+ }
438
+ });
439
+ // Resume a paused sandbox
440
+ sandboxCommand
441
+ .command('resume <sandbox-id>')
442
+ .description('Resume a paused sandbox (a fresh pod on the same workspace)')
443
+ .option('--no-wait', 'Return as soon as the resume has started (202 resuming)')
444
+ .option('--timeout <seconds>', 'Longest wait for the sandbox to be running (max 120)')
445
+ .option('--json', 'Output as JSON')
446
+ .action(async (sandboxId, options) => {
447
+ const timeoutSeconds = options.timeout !== undefined
448
+ ? parseIntOption(options.timeout, { label: 'timeout', min: 1, max: 120 })
449
+ : undefined;
450
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
451
+ if (dryRunGuard(globalOpts, 'sandbox resume', {
452
+ 'Sandbox ID': sandboxId,
453
+ 'Wait': options.wait !== false ? 'yes' : 'no',
454
+ }))
455
+ return;
456
+ const spinner = ora('Resuming sandbox...').start();
457
+ try {
458
+ const client = getClient();
459
+ const result = await client.sandbox.resume(sandboxId, { wait: options.wait !== false, timeoutSeconds });
460
+ if (result?.sandbox_id !== sandboxId || !['running', 'resuming'].includes(result.status)) {
461
+ throw new Error('Sandbox resume was not confirmed for the requested sandbox.');
462
+ }
463
+ spinner.stop();
464
+ const format = resolveFormat({ ...options, ...globalOpts });
465
+ if (format !== 'table') {
466
+ const { formatSingleOutput } = await import('../utils/output.js');
467
+ console.log(formatSingleOutput(result, { format }));
468
+ return;
469
+ }
470
+ if (result.status === 'resuming') {
471
+ console.log(chalk.yellow(`Sandbox ${sandboxId} is resuming`));
472
+ return;
473
+ }
474
+ console.log(chalk.green(`Sandbox ${sandboxId} is running`));
475
+ if (result.expires_at)
476
+ console.log(chalk.gray('Expires at:'), result.expires_at);
184
477
  }
185
478
  catch (error) {
186
- spinner.fail('Failed to stop sandbox');
187
- console.error(chalk.red(formatCliError(error)));
188
- process.exit(1);
479
+ handleCommandError(error, spinner, { mutationRecovery: sandboxRecovery });
189
480
  }
190
481
  });
191
482
  // Extend sandbox lifetime
@@ -195,24 +486,32 @@ sandboxCommand
195
486
  .option('-s, --seconds <seconds>', 'Additional lifetime in seconds', '900')
196
487
  .option('--json', 'Output as JSON')
197
488
  .action(async (sandboxId, options) => {
489
+ const seconds = parseIntOption(options.seconds, { label: 'seconds', min: 60 });
490
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
491
+ if (dryRunGuard(globalOpts, 'sandbox extend', {
492
+ 'Sandbox ID': sandboxId,
493
+ 'Additional seconds': seconds,
494
+ }))
495
+ return;
198
496
  const spinner = ora('Extending sandbox lifetime...').start();
199
497
  try {
200
- const seconds = parseIntOption(options.seconds, { label: 'seconds', min: 60 });
201
498
  const client = getClient();
202
499
  const result = await client.sandbox.extend(sandboxId, seconds);
500
+ const sandbox = toSandboxView(result);
203
501
  spinner.stop();
204
- if (options.json) {
205
- console.log(JSON.stringify(result, null, 2));
502
+ const format = resolveFormat({ ...options, ...globalOpts });
503
+ if (format !== 'table') {
504
+ const { formatSingleOutput } = await import('../utils/output.js');
505
+ console.log(formatSingleOutput(result, { format }));
206
506
  return;
207
507
  }
208
- const extensionMetadata = result;
209
- const requestedSeconds = typeof extensionMetadata.requested_additional_seconds === 'number'
210
- ? extensionMetadata.requested_additional_seconds
508
+ const requestedSeconds = typeof sandbox.requestedAdditionalSeconds === 'number'
509
+ ? sandbox.requestedAdditionalSeconds
211
510
  : seconds;
212
- const appliedSeconds = typeof extensionMetadata.applied_additional_seconds === 'number'
213
- ? extensionMetadata.applied_additional_seconds
214
- : (typeof extensionMetadata.additional_seconds === 'number'
215
- ? extensionMetadata.additional_seconds
511
+ const appliedSeconds = typeof sandbox.appliedAdditionalSeconds === 'number'
512
+ ? sandbox.appliedAdditionalSeconds
513
+ : (typeof sandbox.additionalSeconds === 'number'
514
+ ? sandbox.additionalSeconds
216
515
  : requestedSeconds);
217
516
  if (appliedSeconds < requestedSeconds) {
218
517
  console.log(chalk.yellow(`Sandbox ${sandboxId} extension capped at ${formatDuration(appliedSeconds)} (requested ${formatDuration(requestedSeconds)})`));
@@ -220,17 +519,15 @@ sandboxCommand
220
519
  else {
221
520
  console.log(chalk.green(`Sandbox ${sandboxId} extended by ${formatDuration(appliedSeconds)}`));
222
521
  }
223
- console.log(chalk.gray('Status:'), result.status);
224
- console.log(chalk.gray('Expires at:'), result.expires_at);
225
- const remainingExtendSeconds = result.remaining_extend_seconds;
522
+ console.log(chalk.gray('Status:'), sandbox.status);
523
+ console.log(chalk.gray('Expires at:'), sandbox.expiresAt);
524
+ const remainingExtendSeconds = sandbox.remainingExtendSeconds;
226
525
  if (typeof remainingExtendSeconds === 'number') {
227
526
  console.log(chalk.gray('Remaining extend budget:'), formatRemainingExtendBudget(remainingExtendSeconds));
228
527
  }
229
528
  }
230
529
  catch (error) {
231
- spinner.fail('Failed to extend sandbox');
232
- console.error(chalk.red(formatCliError(error)));
233
- process.exit(1);
530
+ handleCommandError(error, spinner, { mutationRecovery: sandboxRecovery });
234
531
  }
235
532
  });
236
533
  // Write file to sandbox
@@ -238,6 +535,13 @@ sandboxCommand
238
535
  .command('write <sandbox-id> <path> <content>')
239
536
  .description('Write a file to a sandbox')
240
537
  .action(async (sandboxId, path, content) => {
538
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
539
+ if (dryRunGuard(globalOpts, 'sandbox write', {
540
+ 'Sandbox ID': sandboxId,
541
+ Path: path,
542
+ 'Content length': `${content.length} chars`,
543
+ }))
544
+ return;
241
545
  const spinner = ora('Writing file...').start();
242
546
  try {
243
547
  const client = getClient();
@@ -245,9 +549,7 @@ sandboxCommand
245
549
  spinner.succeed(`File written to ${path}`);
246
550
  }
247
551
  catch (error) {
248
- spinner.fail('Failed to write file');
249
- console.error(chalk.red(formatCliError(error)));
250
- process.exit(1);
552
+ handleCommandError(error, spinner, { mutationRecovery: workspaceRecovery });
251
553
  }
252
554
  });
253
555
  // Read file from sandbox
@@ -258,14 +560,12 @@ sandboxCommand
258
560
  const spinner = ora('Reading file...').start();
259
561
  try {
260
562
  const client = getClient();
261
- const content = await client.sandbox.readFile(sandboxId, path);
563
+ const content = await withRetry(() => client.sandbox.readFile(sandboxId, path), { spinner });
262
564
  spinner.stop();
263
- console.log(typeof content === 'string' ? content : content.content);
565
+ console.log(fileReadBytes(content).toString('utf8'));
264
566
  }
265
567
  catch (error) {
266
- spinner.fail('Failed to read file');
267
- console.error(chalk.red(formatCliError(error)));
268
- process.exit(1);
568
+ handleCommandError(error, spinner);
269
569
  }
270
570
  });
271
571
  // List files in sandbox
@@ -280,10 +580,18 @@ sandboxCommand
280
580
  const spinner = ora('Listing files...').start();
281
581
  try {
282
582
  const client = getClient();
283
- const result = await client.sandbox.listFiles(sandboxId, options.path, { recursive: options.recursive });
583
+ const result = await withRetry(() => client.sandbox.listFiles(sandboxId, options.path, { recursive: options.recursive }), { spinner });
284
584
  spinner.stop();
285
- if (options.json) {
286
- console.log(JSON.stringify(result.files, null, 2));
585
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
586
+ const format = resolveFormat({ ...options, ...globalOpts });
587
+ if (format !== 'table') {
588
+ const fileColumns = [
589
+ { key: 'name', header: 'Name' },
590
+ { key: 'type', header: 'Type' },
591
+ { key: 'size', header: 'Size', transform: (v) => formatFileSize(v) },
592
+ { key: 'modified_at', header: 'Modified', transform: (v) => formatDateTime(v) },
593
+ ];
594
+ console.log(formatOutput(result.files, { format, columns: fileColumns, emptyMessage: 'No files found' }));
287
595
  return;
288
596
  }
289
597
  if (result.files.length === 0) {
@@ -302,9 +610,146 @@ sandboxCommand
302
610
  console.log(table(tableData));
303
611
  }
304
612
  catch (error) {
305
- spinner.fail('Failed to list files');
306
- console.error(chalk.red(formatCliError(error)));
307
- process.exit(1);
613
+ handleCommandError(error, spinner);
614
+ }
615
+ });
616
+ // Glob files
617
+ sandboxCommand
618
+ .command('glob <sandbox-id> <pattern>')
619
+ .description('Find files matching a glob pattern')
620
+ .option('--json', 'Output as JSON')
621
+ .action(async (sandboxId, pattern, options) => {
622
+ const spinner = ora('Searching files...').start();
623
+ try {
624
+ const client = getClient();
625
+ const result = await withRetry(() => client.sandbox.glob(sandboxId, pattern), { spinner });
626
+ const files = Array.isArray(result) ? result : result.files || [];
627
+ spinner.stop();
628
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
629
+ const format = resolveFormat({ ...options, ...globalOpts });
630
+ if (format !== 'table') {
631
+ console.log(formatOutput(files.map((f) => ({ path: f })), {
632
+ format,
633
+ columns: [{ key: 'path', header: 'Path' }],
634
+ emptyMessage: 'No files matched',
635
+ }));
636
+ return;
637
+ }
638
+ if (files.length === 0) {
639
+ console.log(chalk.yellow('No files matched'));
640
+ return;
641
+ }
642
+ for (const file of files) {
643
+ console.log(file);
644
+ }
645
+ console.log();
646
+ console.log(chalk.gray(`${files.length} file(s) matched`));
647
+ }
648
+ catch (error) {
649
+ handleCommandError(error, spinner);
650
+ }
651
+ });
652
+ // Create directory
653
+ sandboxCommand
654
+ .command('mkdir <sandbox-id> <path>')
655
+ .description('Create a directory in a sandbox')
656
+ .option('-r, --recursive', 'Create parent directories as needed')
657
+ .action(async (sandboxId, path, options) => {
658
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
659
+ if (dryRunGuard(globalOpts, 'sandbox mkdir', {
660
+ 'Sandbox ID': sandboxId,
661
+ Path: path,
662
+ Recursive: options.recursive ? 'yes' : 'no',
663
+ }))
664
+ return;
665
+ const spinner = ora(`Creating directory ${path}...`).start();
666
+ try {
667
+ const client = getClient();
668
+ await client.sandbox.mkdir(sandboxId, path, options.recursive);
669
+ spinner.succeed(`Directory created: ${path}`);
670
+ }
671
+ catch (error) {
672
+ handleCommandError(error, spinner, { mutationRecovery: workspaceRecovery });
673
+ }
674
+ });
675
+ // Remove file or directory
676
+ sandboxCommand
677
+ .command('rm <sandbox-id> <path>')
678
+ .description('Remove a file or directory from a sandbox')
679
+ .option('-r, --recursive', 'Remove directories recursively')
680
+ .option('-f, --force', 'Skip confirmation')
681
+ .action(async (sandboxId, path, options) => {
682
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
683
+ if (dryRunGuard(globalOpts, 'sandbox rm', {
684
+ 'Sandbox ID': sandboxId,
685
+ Path: path,
686
+ Recursive: options.recursive ? 'yes' : 'no',
687
+ }))
688
+ return;
689
+ if (!options.force) {
690
+ const readline = await import('readline');
691
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
692
+ const answer = await new Promise((resolve) => {
693
+ rl.question(chalk.yellow(`Delete ${path}${options.recursive ? ' recursively' : ''}? [y/N] `), resolve);
694
+ });
695
+ rl.close();
696
+ if (answer.toLowerCase() !== 'y') {
697
+ console.log('Cancelled');
698
+ return;
699
+ }
700
+ }
701
+ const spinner = ora(`Removing ${path}...`).start();
702
+ try {
703
+ const client = getClient();
704
+ await client.sandbox.deleteFile(sandboxId, path, options.recursive);
705
+ spinner.succeed(`Removed: ${path}`);
706
+ }
707
+ catch (error) {
708
+ handleCommandError(error, spinner, { mutationRecovery: workspaceRecovery });
709
+ }
710
+ });
711
+ // Move file
712
+ sandboxCommand
713
+ .command('mv <sandbox-id> <source> <destination>')
714
+ .description('Move or rename a file in a sandbox')
715
+ .action(async (sandboxId, source, destination) => {
716
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
717
+ if (dryRunGuard(globalOpts, 'sandbox mv', {
718
+ 'Sandbox ID': sandboxId,
719
+ Source: source,
720
+ Destination: destination,
721
+ }))
722
+ return;
723
+ const spinner = ora(`Moving ${source} to ${destination}...`).start();
724
+ try {
725
+ const client = getClient();
726
+ await client.sandbox.moveFile(sandboxId, source, destination);
727
+ spinner.succeed(`Moved: ${source} -> ${destination}`);
728
+ }
729
+ catch (error) {
730
+ handleCommandError(error, spinner, { mutationRecovery: workspaceRecovery });
731
+ }
732
+ });
733
+ // Copy file
734
+ sandboxCommand
735
+ .command('cp <sandbox-id> <source> <destination>')
736
+ .description('Copy a file in a sandbox')
737
+ .action(async (sandboxId, source, destination) => {
738
+ const globalOpts = sandboxCommand.parent?.optsWithGlobals?.() ?? {};
739
+ if (dryRunGuard(globalOpts, 'sandbox cp', {
740
+ 'Sandbox ID': sandboxId,
741
+ Source: source,
742
+ Destination: destination,
743
+ }))
744
+ return;
745
+ const spinner = ora(`Copying ${source} to ${destination}...`).start();
746
+ try {
747
+ const client = getClient();
748
+ await client.sandbox.copyFile(sandboxId, source, destination);
749
+ spinner.succeed(`Copied: ${source} -> ${destination}`);
750
+ }
751
+ catch (error) {
752
+ handleCommandError(error, spinner, { mutationRecovery: workspaceRecovery });
308
753
  }
309
754
  });
310
755
  // Helper functions
@@ -313,11 +758,16 @@ function colorStatus(status) {
313
758
  case 'running':
314
759
  return chalk.green(status);
315
760
  case 'creating':
761
+ case 'recovering':
762
+ case 'pausing':
763
+ case 'paused':
764
+ case 'resuming':
316
765
  return chalk.yellow(status);
317
766
  case 'terminated':
318
767
  case 'terminating':
319
768
  return chalk.gray(status);
320
769
  case 'error':
770
+ case 'recovery_failed':
321
771
  return chalk.red(status);
322
772
  default:
323
773
  return status;
@@ -366,4 +816,8 @@ function formatBudgetDuration(seconds) {
366
816
  }
367
817
  return `${clampedSeconds}s`;
368
818
  }
819
+ // ps / logs / kill / spawn: supervised background processes
820
+ registerProcessCommands(sandboxCommand);
821
+ registerTimelineCommand(sandboxCommand);
822
+ registerSandboxEgressCommand(sandboxCommand);
369
823
  //# sourceMappingURL=sandbox.js.map