refactor(sandbox): make the bound file backend the run's single session handle (#1292)

* feat(sandbox): add run_commands to SandboxFileBackend

* refactor(git): thread bound sandbox backend through git/publish path

* refactor(sandbox): run bash through the bound backend; thread it to subagents

* test(sandbox): guard that the backend never advertises execution

* feat(sandbox): classify bash failures as transient or permanent

The bash tool degraded every transport/HTTP error to the same generic
"sandbox call failed" string, so the agent could not tell a momentary
blip (worth one retry) from a non-recoverable rejection (stop using the
tool). Introduce a BashFailure enum that maps httpx errors to TRANSIENT
(no response, or a retryable status: 408/425/429/5xx) vs PERMANENT
(auth, session-gone, bad-request, not-implemented), and return distinct
agent-facing guidance for each. The transient message is byte-stable so
the system prompt's "two identical error strings => stop" backstop still
fires when a retry fails the same way.

Non-httpx failures (malformed 200 body, unbound-backend RuntimeError)
are left to propagate as loud wire/programming bugs.

Author: srtab

daiv/automation/agent/git_manager.py

@@ -10,12 +10,11 @@
 from git import GitCommandError
 
 from automation.agent.constants import REPO_PATH
-from core.sandbox.schemas import RunCommandsRequest
 
 if TYPE_CHECKING:
     from git import Repo
 
-    from core.sandbox.client import DAIVSandboxClient
+    from automation.agent.middlewares.file_system import SandboxFileBackend
 
 logger = logging.getLogger("daiv.tools")
 
@@ -56,9 +55,9 @@ class RepoStatus:
 class GitManager:
     """Run git operations against a repository in one of two mutually-exclusive modes:
 
-    - **Sandbox mode** (``client`` + ``session_id``): git runs *in the sandbox* via
-      ``run_commands`` in ``repo_path`` (``/workspace/repo``). Used for sandbox-enabled
-      runs, where the agent's changes are sandbox-authoritative (no local copy).
+    - **Sandbox mode** (``sandbox_backend``): git runs *in the sandbox* via the bound
+      backend's ``run_commands`` in ``repo_path`` (``/workspace/repo``). Used for
+      sandbox-enabled runs, where the agent's changes are sandbox-authoritative (no local copy).
     - **Local mode** (``repo``): git runs as a subprocess against a GitPython clone's
       working tree. Used for sandbox-disabled / repoless runs, where changes live on disk.
 
@@ -67,8 +66,7 @@ class GitManager:
 
     Args:
         repo: GitPython repo for local mode.
-        client: Sandbox client for sandbox mode.
-        session_id: Sandbox session id (required with ``client``).
+        sandbox_backend: The run's bound :class:`SandboxFileBackend` for sandbox mode.
         repo_path: Repo path inside the sandbox (defaults to ``REPO_PATH``).
     """
 
@@ -78,19 +76,15 @@ def __init__(
         self,
         repo: Repo | None = None,
         *,
-        client: DAIVSandboxClient | None = None,
-        session_id: str | None = None,
+        sandbox_backend: SandboxFileBackend | None = None,
         repo_path: str | None = None,
     ) -> None:
-        if (repo is None) == (client is None):
-            raise ValueError("GitManager requires exactly one of `repo` (local) or `client` (sandbox).")
-        if client is not None and not session_id:
-            raise ValueError("GitManager sandbox mode requires a non-empty session_id.")
+        if (repo is None) == (sandbox_backend is None):
+            raise ValueError("GitManager requires exactly one of `repo` (local) or `sandbox_backend` (sandbox).")
         if repo_path is None:
             repo_path = REPO_PATH
         self.repo = repo
-        self._client = client
-        self._session_id = session_id
+        self._sandbox_backend = sandbox_backend
         self._repo_path = repo_path
 
     @classmethod
@@ -103,30 +97,31 @@ def for_local(cls, repo: Repo) -> GitManager:
         return cls(repo=repo)
 
     @classmethod
-    def for_sandbox(cls, client: DAIVSandboxClient, session_id: str, *, repo_path: str | None = None) -> GitManager:
+    def for_sandbox(cls, sandbox_backend: SandboxFileBackend, *, repo_path: str | None = None) -> GitManager:
         """Sandbox-mode manager that runs git in the session's ``repo_path`` (``/workspace/repo``).
 
-        Preferred over ``GitManager(client=..., session_id=...)``: the required ``session_id`` is
-        positional, so a sandbox manager can't be built without one.
+        Takes the run's already-bound :class:`SandboxFileBackend` — the single session handle.
+        The backend's ``_require_bound`` guard surfaces an unbound-session programming error on
+        the first command, so no session id is threaded here.
         """
-        return cls(client=client, session_id=session_id, repo_path=repo_path)
+        return cls(sandbox_backend=sandbox_backend, repo_path=repo_path)
 
     # -- git invocation ------------------------------------------------------
     async def _git(self, *args: str, check: bool = True) -> _GitResult:
         """Run one git command in the repo. Raises ``GitCommandError`` on a non-zero
         exit when ``check`` is True; otherwise returns the result for the caller to inspect.
         """
-        result = await (self._git_sandbox(args) if self._client is not None else self._git_local(args))
+        result = await (self._git_sandbox(args) if self._sandbox_backend is not None else self._git_local(args))
         if check and result.exit_code != 0:
             raise GitCommandError(["git", *args], result.exit_code, result.output)
         return result
 
     async def _git_sandbox(self, args: tuple[str, ...]) -> _GitResult:
-        client, session_id = self._client, self._session_id
-        if client is None or session_id is None:  # pragma: no cover - guaranteed by __init__
+        backend = self._sandbox_backend
+        if backend is None:  # pragma: no cover - guaranteed by __init__
             raise RuntimeError("GitManager is not in sandbox mode")
         command = " ".join(_shell_quote(token) for token in ("git", "-C", self._repo_path, *args))
-        response = await client.run_commands(session_id, RunCommandsRequest(commands=[command], fail_fast=True))
+        response = await backend.run_commands([command], fail_fast=True)
         if not response.results:
             # The sandbox always returns one result per command; an empty list is a wire-level
             # anomaly. Fail with context rather than a bare IndexError on ``results[0]``.
@@ -159,14 +154,11 @@ async def _git_batch(self, commands: list[tuple[str, ...]]) -> list[_GitResult]:
         """
         if not commands:
             return []
-        if self._client is not None:
-            client, session_id = self._client, self._session_id
-            if session_id is None:  # pragma: no cover - guaranteed by __init__
-                raise RuntimeError("GitManager is not in sandbox mode")
+        if self._sandbox_backend is not None:
             cmd_strs = [
                 " ".join(_shell_quote(tok) for tok in ("git", "-C", self._repo_path, *args)) for args in commands
             ]
-            response = await client.run_commands(session_id, RunCommandsRequest(commands=cmd_strs, fail_fast=False))
+            response = await self._sandbox_backend.run_commands(cmd_strs, fail_fast=False)
             if len(response.results) != len(commands):
                 raise RuntimeError(f"Sandbox returned {len(response.results)} results for {len(commands)} git commands")
             return [_GitResult(exit_code=r.exit_code, output=r.output) for r in response.results]

daiv/automation/agent/git_utils.py

@@ -10,24 +10,21 @@
 
     from git import Repo
 
-    from core.sandbox.client import DAIVSandboxClient
+    from automation.agent.middlewares.file_system import SandboxFileBackend
 
 
 @asynccontextmanager
 async def open_git_manager(
-    *, client: DAIVSandboxClient | None = None, session_id: str | None, gitrepo: Repo | None
+    *, sandbox_backend: SandboxFileBackend | None, gitrepo: Repo | None
 ) -> AsyncIterator[GitManager]:
     """Yield a :class:`GitManager` matched to the run's mode.
 
-    Sandbox-enabled runs (a ``session_id`` is present) get a **sandbox-mode** manager bound to the
-    injected run-scoped ``client`` — git runs in ``/workspace/repo`` where the agent's changes are
-    authoritative. The transport is borrowed, not owned: no open/close here, and no per-call
-    fallback — a session id without a client is a wiring error. Sandbox-disabled / repoless runs
-    (no session) get a **local-mode** manager over the GitPython clone.
+    Sandbox-enabled runs pass the run's bound :class:`SandboxFileBackend` — git runs in
+    ``/workspace/repo`` where the agent's changes are authoritative. Sandbox-disabled /
+    repoless runs pass ``sandbox_backend=None`` and get a local-mode manager over the
+    GitPython clone.
     """
-    if session_id:
-        if client is None:
-            raise RuntimeError("open_git_manager: sandbox session given but no sandbox client injected.")
-        yield GitManager.for_sandbox(client, session_id)
+    if sandbox_backend is not None:
+        yield GitManager.for_sandbox(sandbox_backend)
     else:
         yield GitManager.for_local(cast("Repo", gitrepo))

daiv/automation/agent/graph.py

@@ -264,6 +264,7 @@ async def create_daiv_agent(
             web_fetch_enabled=_web_fetch_enabled,
             fallback_models=fallback_models,
             client=run_client,
+            sandbox_backend=sandbox_backend,
         ),
         create_explore_subagent(backend),
     ]
@@ -278,6 +279,7 @@ async def create_daiv_agent(
         web_fetch_enabled=_web_fetch_enabled,
         fallback_models=fallback_models,
         client=run_client,
+        sandbox_backend=sandbox_backend,
     )
     subagents.extend(custom_subagents)
 
@@ -314,7 +316,7 @@ async def create_daiv_agent(
         AnthropicPromptCachingMiddleware(),
         ToolCallLoggingMiddleware(),
         ensure_non_empty_response,
-        GitMiddleware(auto_commit_changes=auto_commit_changes, sandbox_client=run_client),
+        GitMiddleware(auto_commit_changes=auto_commit_changes, sandbox_backend=sandbox_backend),
         GitPlatformMiddleware(git_platform=ctx.git_platform, backend=backend),
         dynamic_daiv_system_prompt,
         *(middleware or []),

daiv/automation/agent/middlewares/file_system.py

@@ -40,6 +40,8 @@
     FsLsRequest,
     FsReadRequest,
     FsWriteRequest,
+    RunCommandsRequest,
+    RunCommandsResponse,
 )
 
 logger = logging.getLogger("daiv.tools")
@@ -204,7 +206,8 @@ def resolve_backend_for(self, virtual_path: str) -> BackendProtocol:
 
 
 class SandboxFileBackend(BackendProtocol):
-    """Deepagents backend whose files live in a sandbox workspace.
+    """Deepagents backend whose files live in a sandbox workspace, and the run's
+    command-execution handle (``run_commands``).
 
     The agent addresses files by their sandbox-absolute path (``/workspace/repo``,
     ``/workspace/skills``, ``/workspace/tmp``); the backend is a thin pass-through to
@@ -251,6 +254,21 @@ def _require_bound(self) -> tuple[DAIVSandboxClient, str]:
             raise RuntimeError("SandboxFileBackend is not bound to a sandbox session")
         return self._client, self._session_id
 
+    async def run_commands(self, commands: list[str], *, fail_fast: bool) -> RunCommandsResponse:
+        """Run shell commands in the bound session's workspace.
+
+        The run's command-execution handle (used by the ``bash`` tool and sandbox-mode
+        ``GitManager``). A thin pass-through to ``DAIVSandboxClient.run_commands`` — it takes a
+        *list* + ``fail_fast`` (not a single command) so multi-command batches run in one
+        round-trip. Like the other methods here it **raises** on transport/HTTP errors;
+        callers that need graceful degradation (the ``bash`` tool) wrap it.
+
+        Intentionally NOT deepagents' ``SandboxBackendProtocol.aexecute``: implementing that
+        protocol would activate deepagents' always-registered, ungated ``execute`` tool.
+        """
+        client, session_id = self._require_bound()
+        return await client.run_commands(session_id, RunCommandsRequest(commands=commands, fail_fast=fail_fast))
+
     # -- path mapping (identity) --------------------------------------------
     # The sandbox is authoritative and the agent addresses files by their
     # sandbox-absolute path (/workspace/repo, /workspace/skills, /workspace/tmp).

daiv/automation/agent/middlewares/git.py

@@ -29,7 +29,7 @@
 
     from langgraph.runtime import Runtime
 
-    from core.sandbox.client import DAIVSandboxClient
+    from automation.agent.middlewares.file_system import SandboxFileBackend
 
 
 logger = logging.getLogger("daiv.tools")
@@ -104,9 +104,9 @@ class GitMiddleware(AgentMiddleware[GitState, RuntimeCtx]):
         skip_ci: Whether to prefix the commit with ``[skip ci]``.
         auto_commit_changes: Whether the run publishes its changes at all. When ``False`` the
             middleware is inert.
-        sandbox_client: Run-scoped sandbox client injected by ``create_daiv_agent``; forwarded to
-            :class:`GitChangePublisher` so the turn-end publish runs git inside the sandbox. ``None``
-            for sandbox-disabled / local runs.
+        sandbox_backend: Run's bound :class:`SandboxFileBackend` injected by ``create_daiv_agent``;
+            forwarded to :class:`GitChangePublisher` so the turn-end publish runs git inside the
+            sandbox. ``None`` for sandbox-disabled / local runs.
 
     Example:
         ```python
@@ -131,14 +131,14 @@ def __init__(
         *,
         skip_ci: bool = False,
         auto_commit_changes: bool = True,
-        sandbox_client: DAIVSandboxClient | None = None,
+        sandbox_backend: SandboxFileBackend | None = None,
     ) -> None:
         """
         Initialize the middleware.
         """
         self.skip_ci = skip_ci
         self.auto_commit_changes = auto_commit_changes
-        self._sandbox_client = sandbox_client
+        self._sandbox_backend = sandbox_backend
 
     async def abefore_agent(self, state: GitState, runtime: Runtime[RuntimeCtx]) -> dict[str, Any] | None:
         """
@@ -260,10 +260,8 @@ async def aafter_agent(self, state: GitState, runtime: Runtime[RuntimeCtx]) -> d
         if not self.auto_commit_changes:
             return None
 
-        publisher = GitChangePublisher(runtime.context, sandbox_client=self._sandbox_client)
-        outcome = await publisher.publish(
-            session_id=state.get("session_id"), merge_request=state.get("merge_request"), skip_ci=self.skip_ci
-        )
+        publisher = GitChangePublisher(runtime.context, sandbox_backend=self._sandbox_backend)
+        outcome = await publisher.publish(merge_request=state.get("merge_request"), skip_ci=self.skip_ci)
 
         if outcome.merge_request is None:
             return None