solari-runloop-compat 0.2.9__tar.gz → 0.2.11__tar.gz

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 (55) hide show
  1. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/COMPAT.md +7 -0
  2. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/PKG-INFO +2 -2
  3. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/pyproject.toml +2 -2
  4. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/__init__.py +1 -1
  5. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_gateway.py +64 -11
  6. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_mapping.py +18 -0
  7. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/.gitignore +0 -0
  8. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/LICENSE +0 -0
  9. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/NOTICE +0 -0
  10. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/README.md +0 -0
  11. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_branding.py +0 -0
  12. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_client.py +0 -0
  13. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_config.py +0 -0
  14. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_context.py +0 -0
  15. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_dockerfile.py +0 -0
  16. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_exceptions.py +0 -0
  17. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_loop.py +0 -0
  18. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_models.py +0 -0
  19. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_options.py +0 -0
  20. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_redact.py +0 -0
  21. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_resources.py +0 -0
  22. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_sync.py +0 -0
  23. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_types.py +0 -0
  24. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/_vendor_user.py +0 -0
  25. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/lib/__init__.py +0 -0
  26. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/lib/polling.py +0 -0
  27. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/pagination.py +0 -0
  28. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/sdk.py +0 -0
  29. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/__init__.py +0 -0
  30. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/blueprint_build_log.py +0 -0
  31. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/blueprint_build_logs_list_view.py +0 -0
  32. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/blueprint_build_parameters.py +0 -0
  33. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/blueprint_list_view.py +0 -0
  34. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/blueprint_view.py +0 -0
  35. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devbox_async_execution_detail_view.py +0 -0
  36. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devbox_execution_detail_view.py +0 -0
  37. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devbox_snapshot_list_view.py +0 -0
  38. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devbox_snapshot_view.py +0 -0
  39. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devbox_view.py +0 -0
  40. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devboxes/__init__.py +0 -0
  41. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devboxes/devbox_logs_list_view.py +0 -0
  42. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devboxes/devbox_snapshot_async_status_view.py +0 -0
  43. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/devboxes/execution_update_chunk.py +0 -0
  44. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/object_download_url_view.py +0 -0
  45. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/object_view.py +0 -0
  46. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/secret_list_view.py +0 -0
  47. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/secret_view.py +0 -0
  48. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/__init__.py +0 -0
  49. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/after_idle.py +0 -0
  50. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/code_mount_parameters.py +0 -0
  51. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/launch_parameters.py +0 -0
  52. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/lifecycle_configuration.py +0 -0
  53. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/lifecycle_hooks.py +0 -0
  54. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/shared/resume_triggers.py +0 -0
  55. {solari_runloop_compat-0.2.9 → solari_runloop_compat-0.2.11}/solari_runloop/types/tunnel_view.py +0 -0
@@ -63,6 +63,7 @@ exactly Runloop's parameters. Details that differ from what the old signatures l
63
63
  - `executions.kill(kill_process_group=True)` and `send_std_in(signal="EOF")` raise (Solari kills the command, and a command handle cannot close stdin); `send_std_in(signal="INTERRUPT")` sends SIGINT to the command. `stream_*_updates` yields the output so far from `offset` and then what the command prints, until it exits (an iterator of `ExecutionUpdateChunk`; it takes no `timeout`).
64
64
  - `attach_stdin` on `execute_async` / `exec_async` is satisfied (the control channel can always be written to with `send_std_in`).
65
65
  - `shutdown(force=True)` is satisfied (Solari's shutdown always shuts down).
66
+ - A resource that does not exist raises `NotFoundError`, as in Runloop: `shutdown` and `get_tunnel` of an unknown devbox, and `snapshot.delete` / `disk_snapshots.delete` of an unknown snapshot (it used to return `{}` or a made-up view). A snapshot delete that the gateway finishes over several passes still ends quietly when a later pass finds it gone.
66
67
  - `list(include_total_count=True)` counts every matching devbox (it follows all pages); without it `total_count` is `None`. A `status` with no Solari state behind it (`failure`, `suspending`, `resuming`) raises instead of returning an empty list.
67
68
  - `list_disk_snapshots` / `disk_snapshots.list`: `devbox_id`, `source_devbox_id`, `limit`, `starting_after`, `name`, `source_blueprint_id` (the snapshot's template) and `include_total_count` are honoured; `total_count` is `None` when more pages exist and the count was not asked for, and when `starting_after` is used. `metadata_key` / `metadata_key_in` raise (Solari cannot filter by metadata).
68
69
  - `retrieve_resource_usage`, `create_ssh_key`, `create_pty_tunnel`, `create_gateway_token`, `create_mcp_token`, `watch_evictions`, `blueprints.preview`: NO, `SolariCompatUnsupported` naming the method. `client.accounts`, `agents`, `axons` (and `axons.events`, `axons.sql`), `apikeys`, `restricted_keys`, `pty`, `network_policies`, `gateway_configs`, `mcp_configs`, `objects`: NO at any depth. `with_raw_response` / `with_streaming_response`: NO.
@@ -126,6 +127,12 @@ import) keep working but still lack the image's `ENV`: rebuild them.
126
127
  `DevboxView` fields Solari does not have are synthesized: `create_time_ms` from `createdAt`, one `state_transitions`
127
128
  entry, `launch_parameters` from the real `cpu`/`memMb`, `capabilities=[]`.
128
129
  - Solari's `stopped` state (guest powered itself off; `POST /sandboxes/:id/start`) has no Runloop equivalent: there is no `Devbox.start`, and a `stopped` sandbox reports status `shutdown` (same as the TypeScript package). Use `solari_sandbox`'s `start()` directly.
130
+ - A suspend ends the command a client is following: the process is saved with the devbox and runs on after a resume, but the execution
131
+ the gateway kept (or the control channel it was read through) is closed. `result()` then raises an `APIError` that says so,
132
+ `exit_status` stays `None`, and `get_state()` says `running` (the process is alive; it is not `completed`) (it used to return at once with `exit_status=None`, which read as success).
133
+ - A control channel the gateway refuses with HTTP 404 (a devbox deleted under a cached handle) is a `NotFoundError`, not an `APIConnectionError`.
134
+ `net.get_tunnel_url(port)` of an authenticated tunnel carries `?slr_token=` (as the TypeScript compat does); an open tunnel's URL stays bare.
135
+ An `async def` log callback is awaited; one that raises is logged and never breaks the execution.
129
136
  - Errors: 400 `BadRequestError`, 401 `AuthenticationError`, 402 and 403 `PermissionDeniedError` (`status_code` keeps 402),
130
137
  404 `NotFoundError`, 409 `ConflictError`, 422 `UnprocessableEntityError`, 429 `RateLimitError`, 5xx `InternalServerError`;
131
138
  network -> `APIConnectionError`, timeouts -> `APITimeoutError`. `.body` is Solari's `{code,error,message,retryable}`.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: solari-runloop-compat
3
- Version: 0.2.9
3
+ Version: 0.2.11
4
4
  Summary: Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop.
5
5
  Project-URL: Homepage, https://getsolari.com
6
6
  Author: Solari
@@ -10,7 +10,7 @@ License-File: NOTICE
10
10
  Keywords: compatibility,runloop,sandbox,solari
11
11
  Requires-Python: >=3.9
12
12
  Requires-Dist: pydantic<3,>=2
13
- Requires-Dist: solari-core>=0.4.0
13
+ Requires-Dist: solari-core>=0.7.11
14
14
  Requires-Dist: solari-sandbox>=0.6.1
15
15
  Provides-Extra: test
16
16
  Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "solari-runloop-compat"
7
- version = "0.2.9"
7
+ version = "0.2.11"
8
8
  description = "Runloop-compatible Python interface over Solari Sandboxes. Not affiliated with Runloop."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
11
11
  license = { text = "MIT" }
12
12
  authors = [{ name = "Solari" }]
13
13
  keywords = ["solari", "sandbox", "runloop", "compatibility"]
14
- dependencies = ["solari-sandbox>=0.6.1", "solari-core>=0.4.0", "pydantic>=2,<3"]
14
+ dependencies = ["solari-sandbox>=0.6.1", "solari-core>=0.7.11", "pydantic>=2,<3"]
15
15
 
16
16
  [project.optional-dependencies]
17
17
  test = ["pytest>=7", "pytest-asyncio>=0.23"]
@@ -33,7 +33,7 @@ from ._types import NOT_GIVEN, NoneType, NotGiven, Omit, Timeout, not_given, omi
33
33
  from .lib.polling import PollingConfig, PollingTimeout
34
34
  from .sdk import AsyncRunloopSDK, RunloopSDK
35
35
 
36
- __version__ = "0.2.9"
36
+ __version__ = "0.2.11"
37
37
  Client = Runloop
38
38
  AsyncClient = AsyncRunloop
39
39
 
@@ -9,6 +9,7 @@ suspend/resume/shutdown so the next call reconnects against the live session.
9
9
  from __future__ import annotations
10
10
 
11
11
  import asyncio
12
+ import inspect
12
13
  import logging
13
14
  import posixpath
14
15
  import shlex
@@ -54,6 +55,16 @@ def _q(s: str) -> str:
54
55
  return quote(s, safe="")
55
56
 
56
57
 
58
+ _CALLBACK_TASKS: "set[asyncio.Task[None]]" = set() # keeps async log callbacks alive until they finish
59
+
60
+
61
+ async def _await_callback(aw: Any) -> None:
62
+ try:
63
+ await aw
64
+ except Exception: # noqa: BLE001 - a user callback must not break the exec
65
+ log.exception("async log callback raised")
66
+
67
+
57
68
  @dataclass
58
69
  class _Exec:
59
70
  execution_id: str
@@ -70,6 +81,7 @@ class _Exec:
70
81
  started_ms: int = field(default_factory=lambda: int(time.time() * 1000))
71
82
  shell_name: Optional[str] = None
72
83
  error: Optional[BaseException] = None
84
+ lost: bool = False # the control channel dropped (a suspend): the process may well be alive, so the state is not "completed"
73
85
  remote: bool = False # started through the gateway's durable executions
74
86
  truncated: Tuple[bool, bool] = (False, False) # (stdout, stderr), as reported by the gateway
75
87
 
@@ -98,7 +110,16 @@ class _Exec:
98
110
  if cb is None:
99
111
  return
100
112
  try:
101
- cb(line)
113
+ res = cb(line)
114
+ if inspect.isawaitable(res): # `async def` callback: run it on the loop (it used to be dropped as "never awaited")
115
+ try:
116
+ task = asyncio.get_running_loop().create_task(_await_callback(res))
117
+ except RuntimeError: # no running loop on this thread
118
+ getattr(res, "close", lambda: None)()
119
+ log.warning("async log callback dropped: no running event loop")
120
+ else:
121
+ _CALLBACK_TASKS.add(task)
122
+ task.add_done_callback(_CALLBACK_TASKS.discard)
102
123
  except Exception: # noqa: BLE001 - a user callback must not break the exec
103
124
  log.exception("log callback raised")
104
125
 
@@ -106,7 +127,7 @@ class _Exec:
106
127
  return DevboxAsyncExecutionDetailView(
107
128
  devbox_id=self.devbox_id,
108
129
  execution_id=self.execution_id,
109
- status=self.status, # type: ignore[arg-type]
130
+ status="running" if self.lost else self.status, # type: ignore[arg-type]
110
131
  exit_status=self.exit_code,
111
132
  stdout=mp.last_n_lines("".join(self.stdout), last_n),
112
133
  stderr=mp.last_n_lines("".join(self.stderr), last_n),
@@ -137,6 +158,7 @@ class Gateway:
137
158
  self._tunnel_api: Optional[bool] = None # gateway has /sandboxes/{id}/tunnel
138
159
  self._deleted_snapshots: set = set() # snapshot ids this client deleted, so query_status can say 'deleted'
139
160
  self._snapshot_sources: Dict[str, str] = {} # snapshot id -> devbox it was made from (the gateway's list does not say yet)
161
+ self._interrupted: set = set() # execution ids the gateway closed because the devbox was suspended (the process lives on)
140
162
  self._durable: Optional[bool] = None # gateway has /sandboxes/{id}/executions
141
163
  self._remote: Dict[str, str] = {} # execution id -> devbox id, for executions started through the durable API
142
164
  self.contexts: Dict[str, Any] = {} # build contexts by object id (in-process; see _context.py)
@@ -307,10 +329,8 @@ class Gateway:
307
329
  pass
308
330
 
309
331
  async def shutdown(self, devbox_id: str) -> DevboxView:
310
- try:
311
- raw = await self.get_raw(devbox_id)
312
- except ex.NotFoundError:
313
- raw = {"sandboxId": devbox_id, "state": "gone", "metadata": {}}
332
+ # A devbox that does not exist is a NotFoundError (the gateway's DELETE of an unknown id answers ok, so it cannot tell).
333
+ raw = await self.get_raw(devbox_id)
314
334
  await self._req("DELETE", f"/sandboxes/{_q(devbox_id)}")
315
335
  await self._drop_handle(devbox_id)
316
336
  raw = dict(raw, state="gone")
@@ -505,7 +525,8 @@ class Gateway:
505
525
  return DevboxAsyncExecutionDetailView(
506
526
  devbox_id=devbox_id,
507
527
  execution_id=d["executionId"],
508
- status=d.get("status", "running"),
528
+ # The gateway closed the record because a suspend cut the channel; the process is saved and runs on after the resume.
529
+ status="running" if d.get("interrupted") == "pause" and d.get("exitCode") is None else d.get("status", "running"),
509
530
  exit_status=d.get("exitCode"),
510
531
  stdout=mp.last_n_lines(d.get("stdout", ""), last_n),
511
532
  stderr=mp.last_n_lines(d.get("stderr", ""), last_n),
@@ -555,6 +576,16 @@ class Gateway:
555
576
  rec.exit_code = final.exit_status
556
577
  rec.stdout, rec.stderr = [final.stdout or ""], [final.stderr or ""]
557
578
  rec.truncated = (bool(final.stdout_truncated), bool(final.stderr_truncated))
579
+ if rec.execution_id in self._interrupted:
580
+ rec.lost = True
581
+ # "completed" with no exit status read as success. The process is saved with the devbox and runs on after a resume;
582
+ # this client just cannot follow it any more.
583
+ rec.error = ex.APIError(
584
+ f"execution {rec.execution_id} was interrupted by a suspend of the devbox: the process is saved with it and keeps running after a resume, "
585
+ "but its output and exit status can no longer be followed. Start the command again (or have it write a log file) to observe it.",
586
+ None,
587
+ body=None,
588
+ )
558
589
  break
559
590
  except Exception as e: # noqa: BLE001
560
591
  # A wait that cannot be answered right now (the devbox is suspended: 409; connection or 5xx while it resumes) says
@@ -581,6 +612,8 @@ class Gateway:
581
612
  raise PollingTimeout("Timed out waiting for execution", await self.remote_get(devbox_id, eid))
582
613
  d = await self._exec_call("POST", f"/sandboxes/{_q(devbox_id)}/executions/{_q(eid)}/wait", {"timeoutMs": int(min(25.0, left if left is not None else 25.0) * 1000)})
583
614
  if d.get("status") == "completed":
615
+ if d.get("interrupted") == "pause" and d.get("exitCode") is None:
616
+ self._interrupted.add(eid)
584
617
  return self._remote_view(d, devbox_id)
585
618
 
586
619
  async def _fresh_request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
@@ -659,6 +692,15 @@ class Gateway:
659
692
  except Exception as e: # noqa: BLE001 - channel dropped before cmd.exit
660
693
  log.warning("execution %s lost its control channel: %s", rec.execution_id, _redact(str(e), rec.devbox_id))
661
694
  rec.exit_code = None
695
+ rec.lost = True
696
+ # No exit status because the channel dropped (a suspend, an expiry), not because the program ended: say so instead of
697
+ # letting result() return a "completed" run with exit_status None.
698
+ rec.error = ex.APIError(
699
+ f"execution {rec.execution_id} lost its control channel before the program reported an exit status (a suspend or the end of the devbox); "
700
+ "if the devbox was suspended the process keeps running after a resume, but this client can no longer follow it.",
701
+ None,
702
+ body=None,
703
+ )
662
704
  rec.flush()
663
705
  rec.status = "completed"
664
706
  assert rec.done is not None
@@ -1048,12 +1090,15 @@ class Gateway:
1048
1090
  {ok: false, status: "deleting"} and keeps the row until a retry finishes. Repeat the same DELETE (bounded, with backoff)."""
1049
1091
  end = time.monotonic() + max_seconds
1050
1092
  pause = 1.0
1093
+ repeat = False
1051
1094
  while True:
1052
1095
  try:
1053
1096
  reply = await self._req("DELETE", f"/snapshots/{_q(snapshot_id)}")
1054
1097
  except ex.NotFoundError:
1098
+ if not repeat:
1099
+ raise # there is no such snapshot
1055
1100
  self._deleted_snapshots.add(snapshot_id)
1056
- return # already gone
1101
+ return # a 404 after a 202 "deleting": the earlier pass finished
1057
1102
  if not (isinstance(reply, dict) and (reply.get("ok") is False or reply.get("status") == "deleting")):
1058
1103
  self._deleted_snapshots.add(snapshot_id)
1059
1104
  return
@@ -1061,6 +1106,7 @@ class Gateway:
1061
1106
  raise ex.RunloopError(f"snapshot {snapshot_id} is still being deleted after {max_seconds:.0f}s: {str(reply.get('error', ''))[:120]}")
1062
1107
  await asyncio.sleep(pause)
1063
1108
  pause = min(pause * 2, 5.0)
1109
+ repeat = True
1064
1110
 
1065
1111
  # --- blueprints (templates) -----------------------------------------------------------
1066
1112
 
@@ -1324,8 +1370,10 @@ class Gateway:
1324
1370
  async def tunnel_get(self, devbox_id: str) -> Any:
1325
1371
  try:
1326
1372
  d = await self._tunnel_call(devbox_id, "GET")
1327
- except ex.NotFoundError:
1328
- return None # no tunnel enabled: Runloop's get_tunnel returns None
1373
+ except ex.NotFoundError as e:
1374
+ if isinstance(e.body, dict) and e.body.get("code") == "TunnelNotEnabled":
1375
+ return None # no tunnel enabled: Runloop's get_tunnel returns None
1376
+ raise # a devbox that does not exist
1329
1377
  if d is None:
1330
1378
  return await self.tunnel_view(devbox_id)
1331
1379
  return self._tunnel_obj(d)
@@ -1340,7 +1388,12 @@ class Gateway:
1340
1388
  return None
1341
1389
  template = getattr(t, "url_template", None)
1342
1390
  if template:
1343
- return template.replace("{port}", str(port))
1391
+ url = template.replace("{port}", str(port))
1392
+ # An authenticated tunnel answers 401 to a bare URL; the TypeScript compat returns the URL with the tunnel's token, so does this.
1393
+ token = getattr(t, "auth_token", None)
1394
+ if token and getattr(t, "auth_mode", None) == "authenticated" and "slr_token=" not in url:
1395
+ url += ("&" if "?" in url else "?") + "slr_token=" + quote(token, safe="")
1396
+ return url
1344
1397
  return (await self.preview_url(devbox_id, port)).get("url")
1345
1398
 
1346
1399
  async def tunnel_view(self, devbox_id: str, port: int = 8080) -> Any:
@@ -403,6 +403,15 @@ def create_body(
403
403
  # --- errors ---------------------------------------------------------------------------------
404
404
 
405
405
 
406
+ #: A file path the guest's image-root guard refused (a devbox built from an image): it resolves outside the image root,
407
+ #: through a magic link such as /proc/1/root, or across a mount. Runloop answers that with PermissionDenied. Newer guest
408
+ #: agents say "path escapes the image root"; the "verify ..." forms are what agents already baked into goldens say.
409
+ ROOT_ESCAPE_RE = re.compile(
410
+ r'path escapes the image root|verify "[^"]*": (?:resolved to .*outside the root|too many levels of symbolic links'
411
+ r"|invalid cross-device link|operation not permitted|resolves to a different file)"
412
+ )
413
+
414
+
406
415
  def map_error(exc: BaseException) -> BaseException:
407
416
  """``solari_core`` error -> the Runloop exception a Runloop caller would catch."""
408
417
  if isinstance(exc, ex.RunloopError):
@@ -439,9 +448,18 @@ def map_error(exc: BaseException) -> BaseException:
439
448
  out2.__cause__ = exc
440
449
  return out2
441
450
  if isinstance(exc, core_errors.ConnectionError):
451
+ # The control channel of a devbox that was deleted under a cached handle: the gateway refuses the upgrade with HTTP 404.
452
+ if "websocket" in exc.message.lower() and re.search(r"\bHTTP 404\b", exc.message):
453
+ nf404 = ex.NotFoundError(exc.message, body={"message": exc.message})
454
+ nf404.__cause__ = exc
455
+ return nf404
442
456
  out3 = ex.APIConnectionError(exc.message)
443
457
  out3.__cause__ = exc
444
458
  return out3
459
+ if isinstance(exc, core_errors.ActionError) and str(exc.method or "").startswith("fs.") and ROOT_ESCAPE_RE.search(exc.message or ""):
460
+ out5 = ex.PermissionDeniedError(exc.message, status_code=403, body={"code": "PathOutsideRoot", "error": exc.message})
461
+ out5.__cause__ = exc
462
+ return out5
445
463
  # A file or directory that does not exist is Runloop's 404, not a bare APIError: the guest answers the RPC with "open <path>: no such file
446
464
  # or directory" and no code (fs.download / fs.list / fs.stat ...).
447
465
  if isinstance(exc, core_errors.ActionError) and str(getattr(exc, "method", "")).startswith("fs.") and "no such file or directory" in exc.message.lower():