Merge remote-tracking branch 'origin/main' into feat/confined-workspace

# Conflicts:
#	CHANGELOG.md

Author: DEENUU1

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`SandboxdWorkspace(session_name=...)` and `DaytonaWorkspace(sandbox_name=...)`.**
+  The workspace is named by whoever configures it rather than by the provider: a
+  run with no ref opens it under the name, or attaches when it exists, so an
+  application can key a session on its own record - a conversation, a user -
+  without storing a ref first. `DockerWorkspace(container_name=...)` did this for
+  Docker in 0.2.31. Two clients opening one name at once end up in one session.
+  A ref is still attach-only, so a run that knows the session existed hears it is
+  gone instead of starting over in an empty one, and a ref naming anything else
+  is left to another capability.
+
 - **`ConfinedWorkspace`.** Pydantic AI's local workspace confines nothing, so moving from
   `LocalBackend(root_dir=...)` to it let the file tools - which usually run without
   approval - write anywhere the process can. `ConfinedWorkspace` wraps any workspace and

docs/concepts/daytona.md

@@ -37,6 +37,16 @@ attaches to it, starting it when Daytona stopped or archived it; one that is des
 gone fails with `WorkspaceUnavailableError`. `destroy(ref)` deletes it. Daytona's own
 auto-stop and auto-delete still apply.
 
+`sandbox_name` names the sandbox instead: a run with no ref creates it under that name, or
+attaches to the sandbox that already has it, so an application can key a sandbox on its
+own record without storing a ref first. Its ref carries the name. Two clients creating
+the same name at once end up in one sandbox. A ref is still attach-only, so a sandbox
+deleted meanwhile is `WorkspaceUnavailableError` rather than a new one.
+
+```python
+sandboxes = DaytonaWorkspace(config=config, sandbox_name=f"conv-{conversation_id}")
+```
+
 ## How a command runs
 
 As a synchronous session command, the one Daytona API that reports stdout and stderr apart

docs/concepts/remote.md

@@ -337,6 +337,27 @@ The service generates session ids, so they are unguessable; an application namin
 its own with `reuse` should derive them from a UUID it generated, never from a
 sequential id or user input, and keep them inside 64 characters.
 
+### A session named by you
+
+`SandboxdWorkspace(session_name=...)` is that from the client: a run with no
+ref opens the session under the name, or attaches when it is open or its files
+are kept, so the application can key the session on its own record - a
+conversation, a user - without storing a ref first:
+
+```python
+sandbox = SandboxdWorkspace(
+    service_url="http://sandboxd:8080",
+    token=token,
+    session_name=f"conv-{conversation_id}",
+)
+```
+
+Two runs opening the same name at once both end up in one session: the service
+answers the second with `409` while the first is still opening it, and the
+client asks again. A ref is still attach-only, so a run continuing a
+conversation whose session was purged gets `WorkspaceUnavailableError` rather
+than an empty directory - hand it the ref when you know the session existed.
+
 ## Making it fast on a small host
 
 Four settings, and on a 4 GB box each one is worth more than it sounds.

src/pydantic_ai_backends/workspaces/_daytona.py

@@ -98,6 +98,11 @@ class DaytonaWorkspaceBackend(WorkspaceBackend, SupportsCommands):
         env: Variables every command gets, under any a call passes.
         client: An `AsyncDaytona` to share, owned and closed by the caller;
             without one each operation opens and closes its own.
+        sandbox_name: A sandbox name chosen by whoever configures the workspace
+            rather than by Daytona: with no ref, the first operation creates the
+            sandbox under it, or attaches to the one that already has it. A ref
+            is still attach-only, so a caller that knows the sandbox existed
+            learns that it is gone instead of starting over in a new one.
     """
 
     def __init__(
@@ -108,9 +113,11 @@ def __init__(
         ref: WorkspaceRef | None = None,
         env: Mapping[str, str] | None = None,
         client: AsyncDaytona | None = None,
+        sandbox_name: str | None = None,
     ) -> None:
         if ref is not None and ref.provider != DAYTONA_PROVIDER:
             raise ValueError(f"expected a {DAYTONA_PROVIDER!r} workspace ref, got {ref.provider!r}")
+        self._sandbox_name = sandbox_name
         self._config = config
         self._create_params = create_params
         self._ref = ref
@@ -137,33 +144,44 @@ async def _daytona(self) -> AsyncIterator[AsyncDaytona]:
 
     async def _sandbox(self, client: AsyncDaytona) -> AsyncSandbox:
         """The sandbox, created or attached under the lock, with a session open in it."""
-        daytona = load("daytona", purpose="DaytonaWorkspace")
         async with self._lock:
-            if self._ref is None:
+            if self._ref is not None:
+                sandbox = await _attach(client, self._ref.id)
+            elif self._sandbox_name is not None:
+                sandbox = await self._open_named(client, self._sandbox_name)
+            else:
                 # Shielded so a caller cancelled mid-create still leaves the ref
                 # of a sandbox Daytona has already made.
                 with anyio.CancelScope(shield=True):
                     sandbox = await client.create(self._create_params)
                     self._ref = WorkspaceRef(provider=DAYTONA_PROVIDER, id=sandbox.id)
-            else:
-                try:
-                    sandbox = await client.get(self._ref.id)
-                except daytona.DaytonaNotFoundError as error:
-                    raise WorkspaceUnavailableError(
-                        f"Daytona sandbox {self._ref.id!r} no longer exists"
-                    ) from error
-                state = _state(sandbox)
-                if state in GONE_STATES:
-                    raise WorkspaceUnavailableError(f"Daytona sandbox {self._ref.id!r} is {state}")
-                if state in RESUMABLE_STATES:
-                    await sandbox.start()
             if self._working_dir is None:
                 self._working_dir = await sandbox.get_work_dir()
             if not self._session_open:
                 await sandbox.process.create_session(self._session_id)
                 self._session_open = True
             return sandbox
 
+    async def _open_named(self, client: AsyncDaytona, name: str) -> AsyncSandbox:
+        """The sandbox called `name`: the existing one, or a new one created under it."""
+        daytona = load("daytona", purpose="DaytonaWorkspace")
+        with anyio.CancelScope(shield=True):
+            try:
+                sandbox = await _attach(client, name)
+            except WorkspaceUnavailableError as gone:
+                if not isinstance(gone.__cause__, daytona.DaytonaNotFoundError):
+                    raise
+                params = self._create_params or daytona.CreateSandboxFromSnapshotParams()
+                try:
+                    sandbox = await client.create(params.model_copy(update={"name": name}))
+                except daytona.DaytonaConflictError:
+                    # Another client created it between our lookup and our create.
+                    sandbox = await _attach(client, name)
+            # The name, not the id: it is what a later client knows to look for,
+            # and `get` takes either.
+            self._ref = WorkspaceRef(provider=DAYTONA_PROVIDER, id=name)
+        return sandbox
+
     async def working_dir(self) -> str:
         """The sandbox's working directory, as Daytona reports it."""
         async with self._daytona() as client:
@@ -264,6 +282,27 @@ async def purge(self) -> None:
             await client.delete(sandbox)
 
 
+async def _attach(client: AsyncDaytona, id_or_name: str) -> AsyncSandbox:
+    """The existing sandbox `id_or_name` names, started when it was stopped or archived.
+
+    Raises:
+        WorkspaceUnavailableError: It does not exist, or is gone for good.
+    """
+    daytona = load("daytona", purpose="DaytonaWorkspace")
+    try:
+        sandbox = await client.get(id_or_name)
+    except daytona.DaytonaNotFoundError as error:
+        raise WorkspaceUnavailableError(
+            f"Daytona sandbox {id_or_name!r} no longer exists"
+        ) from error
+    state = _state(sandbox)
+    if state in GONE_STATES:
+        raise WorkspaceUnavailableError(f"Daytona sandbox {id_or_name!r} is {state}")
+    if state in RESUMABLE_STATES:
+        await sandbox.start()
+    return sandbox
+
+
 @dataclass(kw_only=True)
 class DaytonaWorkspace(AbstractCapability[object]):
     """Supply a Daytona sandbox as the run's workspace.
@@ -300,6 +339,14 @@ class DaytonaWorkspace(AbstractCapability[object]):
     client: AsyncDaytona | None = field(default=None, repr=False, compare=False)
     """An `AsyncDaytona` to share across runs, owned and closed by the caller."""
 
+    sandbox_name: str | None = None
+    """One sandbox for every run, named by you: created on first use, attached after.
+
+    Without it each run without a ref gets a new sandbox and only the ref leads
+    back to it. With it a later process finds the same sandbox by name. A ref
+    naming another sandbox is left to another capability.
+    """
+
     def __post_init__(self) -> None:
         if self.defer_loading:
             raise UserError(
@@ -315,6 +362,7 @@ def backend(self, ref: WorkspaceRef | None = None) -> DaytonaWorkspaceBackend:
             ref=ref,
             env=self.env,
             client=self.client,
+            sandbox_name=self.sandbox_name,
         )
 
     def get_workspace(
@@ -324,6 +372,8 @@ def get_workspace(
         del ctx
         if ref is not None and ref.provider != DAYTONA_PROVIDER:
             return None
+        if ref is not None and self.sandbox_name is not None and ref.id != self.sandbox_name:
+            return None
         return self.backend(ref)
 
     async def destroy(self, ref: WorkspaceRef) -> None:

src/pydantic_ai_backends/workspaces/_sandboxd.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import contextlib
+import re
 import uuid
 from collections.abc import AsyncIterator, Mapping
 from dataclasses import dataclass, field
@@ -45,6 +46,9 @@
 STOP_GRACE_SECONDS = 5.0
 """Longest a cancelled command's stop request may hold up the cancellation."""
 
+OPENING_RETRY_SECONDS = 0.2
+"""Pause before asking again for a named session another client is opening."""
+
 _GONE = frozenset({404, 410})
 """Statuses meaning the session or its sandbox no longer exists."""
 
@@ -84,6 +88,12 @@ class SandboxdWorkspaceBackend(WorkspaceBackend, SupportsCommands):
         client: An `httpx.AsyncClient` to share. Owned by the caller, who
             closes it; without one each request uses a client of its own.
         request_timeout: Seconds for a request that runs no command.
+        session_name: A session id chosen by whoever configures the workspace
+            rather than by the service: with no ref, the first operation opens
+            the session under it, or attaches when it is open or its files are
+            kept. A ref is still attach-only, so a caller that knows the
+            session existed learns that it is gone instead of starting over in
+            an empty one.
     """
 
     def __init__(
@@ -98,9 +108,14 @@ def __init__(
         env: Mapping[str, str] | None = None,
         client: httpx.AsyncClient | None = None,
         request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        session_name: str | None = None,
     ) -> None:
         if ref is not None and ref.provider != provider:
             raise ValueError(f"expected a {provider!r} workspace ref, got {ref.provider!r}")
+        if session_name is not None and not re.fullmatch(wire.SESSION_ID_PATTERN, session_name):
+            raise ValueError(
+                f"session_name {session_name!r} is not a session id the service accepts"
+            )
         self._service_url = service_url.rstrip("/")
         self._token = token
         self._ref = ref
@@ -110,6 +125,7 @@ def __init__(
         self._env = dict(env) if env else None
         self._client = client
         self._request_timeout = request_timeout
+        self._session_name = session_name
         self._session: _Session | None = None
         self._working_dir: str | None = None
         self._lock = anyio.Lock()
@@ -145,15 +161,26 @@ async def _post(
 
     async def _open(self) -> _Session:
         """Open or attach to the session, then learn the service's command ceiling."""
+        named = self._ref is None and self._session_name is not None
         request = wire.CreateSessionRequest(
-            session_id=None if self._ref is None else self._ref.id,
+            session_id=self._session_name if self._ref is None else self._ref.id,
             runtime=self._runtime,
             tenant=self._tenant,
+            reuse=named,
             attach=self._ref is not None,
         )
         response = await self._post(
             "/sessions", request, token=self._token, timeout=self._request_timeout
         )
+        # With `reuse` a 409 means another client is opening the same name right
+        # now - two first runs of one conversation, say. It is theirs a moment
+        # later, so ask again rather than fail one of them.
+        give_up = anyio.current_time() + self._request_timeout
+        while named and response.status_code == 409 and anyio.current_time() < give_up:
+            await anyio.sleep(OPENING_RETRY_SECONDS)
+            response = await self._post(
+                "/sessions", request, token=self._token, timeout=self._request_timeout
+            )
         if self._ref is not None and response.status_code == 404:
             raise WorkspaceUnavailableError(f"sandboxd session {self._ref.id!r} no longer exists")
         response.raise_for_status()
@@ -350,6 +377,15 @@ class SandboxdWorkspace(AbstractCapability[object]):
     client: httpx.AsyncClient | None = field(default=None, repr=False, compare=False)
     """An `httpx.AsyncClient` to share across runs, owned and closed by the caller."""
 
+    session_name: str | None = None
+    """One session for every run, named by you: opened on first use, attached after.
+
+    Without it each run without a ref gets a new session and only the ref leads
+    back to it. With it a later process finds the same session - or the files the
+    service kept after reaping it - by name. A ref naming another session is left
+    to another capability.
+    """
+
     def __post_init__(self) -> None:
         if self.defer_loading:
             raise UserError(
@@ -368,6 +404,7 @@ def backend(self, ref: WorkspaceRef | None = None) -> SandboxdWorkspaceBackend:
             tenant=self.tenant,
             env=self.env,
             client=self.client,
+            session_name=self.session_name,
         )
 
     def get_workspace(
@@ -377,6 +414,8 @@ def get_workspace(
         del ctx
         if ref is not None and ref.provider != self.provider:
             return None
+        if ref is not None and self.session_name is not None and ref.id != self.session_name:
+            return None
         return self.backend(ref)
 
     async def destroy(self, ref: WorkspaceRef) -> None: