feat(workspaces): name sandboxd sessions and Daytona sandboxes (#120)

## Problem

When a run had no ref, the provider always named its session. An
application that keys a sandbox on its own record (a conversation, a
user) therefore had to store each ref before a second run could find the
same files, and two first runs of one conversation opened two sessions.
AgenticOS needs this to move its sandboxd and Daytona workspaces onto
this release (vstorm-co/agenticos#2003, decision 1: "who names a
session"). Before 0.2.30, `RemoteSandbox(session_id=..., reuse=True)`
did exactly this.

## What changes

- **`SandboxdWorkspace(session_name=...)`**: with no ref, the first
operation sends `session_id=<name>` with `reuse`. The service opens the
session or attaches to the open one or to its kept files. A `409`
("Session is opening", from a concurrent open of the same name) is
retried until `request_timeout`, so both runs end up in one session.
Names the service would reject fail at construction.
- **`DaytonaWorkspace(sandbox_name=...)`**: looks the sandbox up by
name, starting a stopped one, or creates it with `name=` added to a copy
of `create_params`. A `DaytonaConflictError` from a concurrent create
attaches instead. The ref carries the name, which `get` accepts.
- **Both:** a ref stays attach-only, so a session purged in the meantime
surfaces as `WorkspaceUnavailableError` rather than an empty directory.
`get_workspace` leaves a ref naming another session to another
capability, as `DockerWorkspace(container_name=...)` does since 0.2.31.
- Docs (`remote.md`, `daytona.md`) and a CHANGELOG `[Unreleased]` entry.

## Verification

- `make test`: 1334 passed, 100% coverage
- `make lint`, `make typecheck` (pyright, 0 errors), `make
typecheck-mypy`: clean
- sandboxd: tested against the real service in-process (uvicorn over
HTTP). Covered: opening under the name, a second client in the same
session, kept files found by name after the session closed, a purged
session behind a ref being unavailable, name validation, routing, the
409 retry, and a 409 that never clears.
- Daytona: the SDK fake learns names. Covered: create under the name
with the caller's params left untouched, attach to and start an existing
one, a conflict, a destroyed one, a ref staying attach-only, routing.

## Limitations

Daytona is not checked against a live account here, the same as the rest
of `DaytonaWorkspace`.

Author: DEENUU1

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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.
+
 ## [0.2.31] - 2026-10-05
 
 ### Added

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: