potpie

GitHub

Context Graph for AI Native SDLC

5,530 stars Python #agents#ai-agents#ai-agents-framework#artificial-intelligence#context-graph#developer-tools#devtools#generative-ai
RAW Doc

Async Migration Plan

Async Migration Plan — Native Libraries, Step by Step

Context

The previous PRs used asyncio.to_thread to wrap blocking calls. The code review flagged:
- Thread-safety bugs (DB sessions passed to worker threads)
- Unbounded queue in custom stream generator
- Daemon thread-per-stream with no cap
- StreamingResponse with sync generator already runs in Starlette's thread pool (~40 tokens) — the custom thread+queue was unnecessary overhead
- Thread pool saturation risk under load

New direction: Replace blocking libraries with native async equivalents. Use to_thread only as a temporary bridge for code that cannot be converted yet. Measure every step.

---

Step 0: Revert thread-based changes

Branch: fix/wait-for-task-start-thread (5 commits)

Revert these changes that introduced asyncio.to_thread wrappers and the custom stream generator:

| File | What to revert |
|------|----------------|
| conversation_routing.py | Remove redis_stream_generator_async, revert start_celery_task_and_stream to sync, remove asyncio.to_thread around ensure_unique_run_id and wait_for_task_start |
| conversations_router.py | Remove asyncio.to_thread wrappers around session_service, redis_manager, ensure_unique_run_id; restore local_mode / request / UA detection in create_conversation |
| conversation_service.py | Remove asyncio.to_thread around history_manager., session_service., redis_manager.*, celery_app.control.revoke |
| redis_streaming.py | Revert stop_event parameter, revert xread block from 1000ms back to 5000ms. Keep require_running in wait_for_task_start (that's a correctness fix, not a threading change) |
| api/router.py | Remove asyncio.to_thread around ensure_unique_run_id |
| tunnel_router.py | Remove asyncio.to_thread wrappers |
| tunnel_service.py | Revert scan_iter and TTL changes only if they were part of the thread PR. Keep if they were independent fixes |
| socket_service.py | Remove close() method if it was added as part of the thread PR |
| main.py | Remove shutdown handler if it was part of the thread PR |
| github_service.py | Remove asyncio.to_thread around redis.get/redis.setex in get_project_structure_async |

Keep from the thread PR:
- wait_for_task_start(require_running=True) — correctness fix, not a threading change
- Timeout additions (timeout=30 on requests calls) — safety fix

Keep from fix/sync-timeouts-only:
- All timeout additions (auth_service, github_service, parse_webhook_helper)
- parsing_controller._query_parsing_status_sync with asyncio.to_thread — acceptable bridge until async DB migration


---

Step 1: AsyncRedisStreamManager for FastAPI

What: Create redis.asyncio client alongside the existing sync client. Add async methods for all operations called from FastAPI.

Files to change:
- redis_streaming.py — add AsyncRedisStreamManager class using redis.asyncio
- async def get_task_status()
- async def set_task_status()
- async def set_task_id()
- async def get_task_id()
- async def publish_event()
- async def set_cancellation()
- async def get_stream_snapshot()
- async def clear_session()
- async def wait_for_task_start() — use asyncio.sleep instead of time.sleep
- conversation_routing.py — use AsyncRedisStreamManager in start_celery_task_and_stream (make it async def), start_celery_task_and_wait
- ensure_unique_run_id → async_ensure_unique_run_id using async Redis
- Leave sync redis_stream_generator as-is (Starlette thread pool handles it)
- session_service.py — add AsyncSessionService using AsyncRedisStreamManager. Use await async_redis.scan(...) instead of keys()
- conversations_router.py — switch to async versions
- api/router.py — switch to async versions
- conversation_service.py — stop_generation uses async Redis methods

Keep unchanged:
- Sync RedisStreamManager — still used by Celery tasks (agent_tasks.py, parsing_tasks.py)
- Sync redis_stream_generator — Starlette runs it in thread pool

Test script: scripts/benchmark_redis_async.py

text
Measures:
1. Time to complete N concurrent POST /message requests (streaming)
2. Time to complete N concurrent GET /active-session requests
3. Time to complete N concurrent GET /task-status requests
4. Compare: before (sync Redis on event loop) vs after (native async Redis)
5. Report: p50, p95, p99 latency; requests/sec; event loop blocked time (via middleware)

PR: feat/async-redis-stream-manager

---

Step 2: AsyncSession for hot-path DB services

What: Migrate services called from FastAPI to use AsyncSession.

2a: UsageService

Why first: Called on every create_conversation and post_message (check_usage_limit). Highest frequency.

- usage_service.py — replace SessionLocal() + session.query() with AsyncSessionLocal + await async_session.execute(select(...))
- Inject AsyncSession from FastAPI dependency

Test script: scripts/benchmark_usage_check.py

text
Measures:
1. N concurrent POST /conversations (each triggers check_usage_limit)
2. Latency distribution before/after

PR: feat/async-usage-service

2b: ChatHistoryService (dual-path) ✅

Why: Used from both FastAPI (store_message, stop_generation) and Celery (agent_tasks). Cannot just swap to async.

- Create AsyncChatHistoryService with AsyncSession:
- async def get_session_history()
- add_message_chunk() (in-memory buffer only)
- async def flush_message_buffer()
- async def save_partial_ai_message()
- ConversationService.create() — accepts optional async_db; when provided, builds AsyncChatHistoryService and uses it on FastAPI path
- FastAPI path uses async variant; Celery path uses existing sync ChatHistoryService

Test script: scripts/benchmark_chat_flow.py

text
Measures:
1. N concurrent POST /message (streaming) — end-to-end including DB writes
2. N concurrent POST /stop — stop_generation with DB save
3. Latency distribution

PR: feat/async-chat-history-service

2c: ShareChatService, AccessService, UserService ✅

- AsyncShareChatService: New class in access_service.py using AsyncSession; share_chat, get_shared_emails, remove_access (select/update/commit).
- conversations_router: Share/access endpoints use get_async_db and AsyncShareChatService(async_db).
- AsyncUserService: New class in user_service.py; async get_user_by_uid, get_user_id_by_email, get_user_by_email, get_user_ids_by_emails, create_user, update_last_login. Sync UserService retained for Celery/main.
- api/router: get_api_key_user uses AsyncUserService(async_db).get_user_by_uid. Auth routes (2d) remain on sync UserService for now.

Test script: scripts/benchmark_share_access.py

text
Measures:
1. N concurrent POST /share
2. N concurrent GET /shared-emails
3. N concurrent DELETE /access

PR: feat/async-share-access-user-services

2d: Auth routes (signup, sso_login, provider endpoints) ✅

- auth_router.py: inject get_async_db, use AsyncUserService(async_db) for user lookups (get_user_by_uid, get_user_by_email, update_last_login) in signup, sso_login, get_my_account
- UnifiedAuthService remains sync for this PR; full async migration can follow

Test script: scripts/benchmark_auth.py

text
Measures:
1. N concurrent POST /signup
2. N concurrent POST /sso/login
3. N concurrent GET /providers/me
4. Latency distribution

PR: feat/async-auth-db

2e: GithubService DB queries ✅

- get_combined_user_repos(user_id, async_session=...) and get_repos_for_user(user_id, async_session=...) accept optional AsyncSession; when provided use select() + await session.execute()
- code_provider_controller.get_user_repos and github_router pass async_db into get_combined_user_repos

PR: feat/async-github-db (included in feat/async-share-access-user-services)

---

Step 3: Async Redis for non-streaming services ✅

What: Add redis.asyncio to services that do simple Redis get/set from FastAPI.

| Service | Change |
|---------|--------|
| tunnel_service.py | ✅ Async client + get_workspace_tunnel_record_async, set_workspace_tunnel_record_async, list_user_tunnels_async. Sync list_user_tunnels uses scan_iter not keys. Workspace record set uses TTL (WORKSPACE_TUNNEL_RECORD_TTL). |
| tunnel_router.py | ✅ Both routes call await tunnel_service.get_workspace_tunnel_record_async(workspace_id). |
| github_service.py | ✅ Lazy shared _get_async_redis_cache(); get_project_structure_async uses async Redis for cache get/setex when available. |
| branch_cache.py | ✅ Optional _async_redis_client; get_branches_async for FastAPI path. Controller get_branch_list uses await branch_cache.get_branches_async. |

Test script: scripts/benchmark_tunnel_github.py

text
Measures:
1. N concurrent GET /tunnel/workspace/{id}
2. N concurrent GET /tunnel/workspace/{id}/socket-status
3. N concurrent GET /github/user-repos (triggers branch cache / repo listing)
4. Latency distribution (p50, p95, p99); req/s
Usage: WORKSPACE_ID=<16-hex> AUTH_HEADER="Bearer <token>" CONCURRENT=5 ROUNDS=2 uv run python scripts/benchmark_tunnel_github.py

PR: feat/async-redis-tunnel-github

---

Step 4: Async HTTP clients ✅

What: Replace requests with httpx where called from FastAPI; offload sync-only SDKs to threads.

| Location | Change |
|----------|--------|
| auth_service.py | Sync login uses httpx.Client; added login_async with httpx.AsyncClient (timeout 10s/30s). Route calls await auth_handler.login_async. |
| auth_router.py | send_slack_message uses httpx.AsyncClient().post with timeout. |
| parse_webhook_helper.py | send_slack_notification uses httpx.AsyncClient().post with timeout. |
| linear_client.py | Sync execute_query uses httpx.Client (timeout 10s/30s); added execute_query_async, get_issue_async, update_issue_async, comment_create_async. Linear tools use async methods. |
| email_helper.py | resend.Emails.send wrapped in await asyncio.to_thread(resend.Emails.send, params) in both send_email and send_parsing_failure_alert. |
| posthog_helper.py | send_event: when event loop is running, uses loop.run_in_executor(None, _capture_sync) (fire-and-forget); otherwise runs _capture_sync inline. |

Test script: scripts/benchmark_login.py (optional; not added in this PR)

PR: Combined with Step 3 in feat/async-redis-tunnel-github

---

Step 5: SearchService async DB

- search_service.py — migrate search_codebase to AsyncSession
- knowledge_graph_router.py — use async session for project verification query

PR: feat/async-search-service

---

Test infrastructure

Shared benchmark harness: scripts/benchmark_harness.py

python
"""
Usage: python scripts/benchmark_harness.py --target <script> --concurrency 10,20,50 --rounds 3
For each concurrency level:
1. Warm up (5 requests)
2. Run N concurrent requests × rounds
3. Report: min, p50, p95, p99, max latency; total wall time; requests/sec
4. Compare with baseline file if provided (--baseline results.json)
"""

Event loop monitor middleware: scripts/eventloop_monitor.py

python
"""
FastAPI middleware that measures event loop blocking.
Logs a warning when any request handler blocks the event loop for > 100ms.
Reports: blocked_time_ms, endpoint, method.
Run with: add middleware to app in development/staging.
"""

Per-step test scripts

Each step has a dedicated script (listed above) that:
1. Hits the actual API endpoints of a running local server
2. Uses httpx.AsyncClient with asyncio.gather for concurrency
3. Requires CONVERSATION_ID, AUTH_TOKEN env vars (real auth against local)
4. Outputs JSON results for before/after comparison
5. Validates: latency improved, no errors, functional correctness (response shape)

---

Execution order and PR strategy

| Order | PR | Risk | Impact |
|-------|-----|------|--------|
| 0 | Revert thread wrappers | Low (restores known-good state) | Removes thread-safety bugs |
| 1 | AsyncRedisStreamManager | Medium (new component) | Unblocks streaming hot path |
| 2a | Async UsageService | Low (isolated) | Unblocks every message send |
| 2b | Async ChatHistoryService | Medium (dual-path) | Unblocks message DB writes |
| 2c | Async Share/Access/User | Low (simple CRUD) | Unblocks sharing endpoints |
| 2d | Async Auth DB | High (large surface) | Unblocks login/signup |
| 2e | Async GitHub DB | Low (small) | Unblocks repo listing |
| 3 | Async Redis (tunnel/github cache) | Low | Unblocks tunnel + cache |
| 4 | Async HTTP clients | Low | Unblocks login, notifications |
| 5 | Async SearchService | Low | Unblocks search |

Each PR:
1. Run benchmark before (on main or previous step)
2. Merge the PR
3. Run benchmark after
4. Record results in docs/async-migration-results.md
5. If regression detected, revert before proceeding

---

What we do NOT change

- Celery tasks — sync by design. No changes.
- Neo4j — all usage is in Celery agent tasks via to_thread(self.run). Fine as-is.
- File I/O / subprocess — all in Celery parsing tasks. Fine.
- Sync redis_stream_generator — Starlette's thread pool handles sync iterators in StreamingResponse. No custom thread/queue.
- to_thread inside Celery's event loop (tool arun methods) — Celery creates its own loop per task; to_thread there is fine.

---

Dependencies to add

text
Already in the project:

redis           # has redis.asyncio built-in
sqlalchemy      # has AsyncSession built-in
httpx           # already used in some places
No new packages needed — all async support is in existing deps.

---

Success criteria

Per step:
- p95 latency for affected endpoints improves or stays flat
- No new errors in logs
- Event loop blocked time (via middleware) decreases
- Thread count (via /proc or metrics) decreases or stays flat

Overall:
- All FastAPI async routes have zero sync I/O on the event loop
- Thread pool usage is only from Starlette's managed pool for StreamingResponse sync generators
- Measured ~30-40% more requests/instance capacity (Duolingo benchmark)

---

Sandbox Core Setup

Sandbox Core Setup

Context

Potpie agents need an isolated place to inspect and change user repositories:
clone once, reuse the repo later, create worktrees for new work, run commands,
edit files, run tests, and resume the same state in a later agent session.

The important distinction is that "sandbox" is not one thing:

- A repo cache is the durable git mirror. It should avoid recloning.
- A workspace is the durable working tree or worktree where the agent sees
files and can make changes.
- A runtime is the compute environment that runs commands against a
workspace. It may be stopped, recreated, or moved without deleting the
workspace.

The hexagonal sandbox module now lives at app/src/sandbox/sandbox/ (domain
ports, application service, API client, outbound adapters). Local mode wires
LocalGitWorkspaceProvider + LocalRepoCacheProvider directly; parsing keeps
using app/modules/repo_manager/repo_manager.py for its own clone/eviction
needs, but sandbox traffic no longer routes through it.

This design keeps the repo/worktree lifecycle separate from the execution
backend. The application layer asks for a workspace, then attaches a runtime to
it.

---

Goals

- Clone a user repo once and reuse it across agent sessions.
- Keep durable agent work in a workspace/worktree, especially for feature work.
- Let multiple execution backends run against the same workspace abstraction:
local container, Docker, Daytona, E2B, or future providers.
- Allow the compute runtime to be hibernated or destroyed without losing the
repo cache or workspace state.
- Support explicit eviction policies for runtimes, workspaces, and repo caches.
- Keep application code backend-agnostic without hiding important persistence
semantics.

Non-goals

- Building a human developer environment like VS Code Remote, Coder, or devpod.
- Making every backend expose identical networking, region, quota, snapshot, or
preview behavior.
- Replacing the existing read-only gvisor_runner.py path immediately.
- Treating snapshots as the only persistence mechanism. Git worktrees and
volumes are first-class persistence.

---

Core Model

RepoCache

A RepoCache is a durable local or remote git mirror for a repository.

In local mode this maps naturally to the existing bare repo:

text
.repos/<owner>/<repo>/.bare/

Responsibilities:

- Normalize repo identity.
- Clone/fetch using the existing auth chain.
- Store metadata needed for eviction and debugging.
- Never hold uncommitted agent edits.

Key rule: repo cache is shared infrastructure. It is not the agent's mutable
working area.

Workspace

A Workspace is a durable checkout/worktree created from a repo cache.

Typical examples:

- Read-only analysis workspace for project_id + base_ref.
- Edit workspace for project_id + conversation_id.
- Task workspace for project_id + task_id.

In local mode this maps to a git worktree:

text
.repos/<owner>/<repo>/worktrees/<user>_<conversation>_<branch>/

Responsibilities:

- Provide a stable filesystem root for an agent session.
- Preserve uncommitted edits, generated files, dependency installs, test
artifacts, and branch state until explicitly cleaned or evicted.
- Track metadata: owner user, project, repo, base ref, branch, dirty state,
last used time, pinned status, and runtime attachment.

Key rule: persistent agent work belongs to a workspace, not to the runtime.

SandboxRuntime

A SandboxRuntime is the compute environment that executes commands against a
workspace.

Examples:

- Local Docker container with workspace mounted.
- Daytona workspace runtime.
- E2B microVM.
- Local read-only gVisor subprocess path for analysis only.

Responsibilities:

- Start, stop, destroy, and report state.
- Execute commands.
- Stream long-running command output.
- Expose optional backend capabilities such as preview URLs or snapshots.

Key rule: destroying a runtime must not delete a workspace unless the caller
explicitly asks for workspace cleanup.

---

Current State (Implemented)

The hexagonal layout described above is in place. References point at code
that is shipped today.

Domain (app/src/sandbox/sandbox/domain/)
- models.py — Workspace, WorkspaceRequest, RepoIdentity, RepoCache
(declared but not yet wired through), Runtime, RuntimeSpec,
ExecRequest, ExecResult, Mount, WorkspaceMode (ANALYSIS/EDIT/
TASK).
- errors.py — WorkspaceError family (WorkspaceNotFound,
RepoCacheUnavailable, RepoAuthFailed, InvalidWorkspacePath, …) and
RuntimeErrorBase family (RuntimeUnavailable, RuntimeTimeout, …).
- ports/workspaces.py, ports/runtimes.py, ports/stores.py,
ports/locks.py — the four ports.

Application (app/src/sandbox/sandbox/application/services/sandbox_service.py)
- SandboxService owns get_or_create_workspace,
get_or_create_runtime, exec, hibernate_runtime,
destroy_runtime, destroy_workspace. Persists workspaces and runtimes
via the store, takes per-workspace locks for mutating commands.

API (app/src/sandbox/sandbox/api/client.py)
- SandboxClient is the public façade. Helpers: read_file,
write_file, list_dir, search, status, diff, commit, push.
Local-fs fast paths when handle.local_path is not None; exec-based
fallbacks otherwise.

Bootstrap (app/src/sandbox/sandbox/bootstrap/)
- settings.py reads SANDBOX_WORKSPACE_PROVIDER /
SANDBOX_RUNTIME_PROVIDER / SANDBOX_REPOS_BASE_PATH /
SANDBOX_METADATA_PATH.
- container.py — build_sandbox_container selects providers and store.

Adapters
- adapters/outbound/local/git_workspace.py — LocalGitWorkspaceProvider.
Bare-repo + worktree creation under .repos/, with
<user>_<scope>_<branch> worktree paths to isolate per-conversation
edits. Currently not used in production — the bridge below overrides
the wiring.
- adapters/outbound/local/subprocess_runtime.py —
LocalSubprocessRuntimeProvider for local exec.
- adapters/outbound/daytona/provider.py — DaytonaWorkspaceProvider and
DaytonaRuntimeProvider. One Daytona sandbox per (user, project),
branch-named worktrees inside it.
- adapters/outbound/docker/runtime.py — DockerRuntimeProvider.
- adapters/outbound/file/json_store.py — JsonSandboxStore (durable
metadata; default for local mode).
- adapters/outbound/memory/store.py, memory/locks.py — in-memory
fallbacks.

Agent tool surface (app/modules/intelligence/tools/sandbox/)
- client.py — process-wide SandboxClient accessor (get_sandbox_client)
and resolve_workspace(...) helper.
- context.py — contextvars (user_id, conversation_id, branch,
auth_token) the agent harness sets at run start.
- tools.py exports create_sandbox_tools() returning four tools:
sandbox_text_editor, sandbox_shell, sandbox_search, sandbox_git.
- tool_functions.py — each tool calls _resolve(project_id, mode=...)
to get a WorkspaceHandle per call.

---

Known Gaps (post-revamp)

Findings from the architectural audit; tracked by the Implementation
Roadmap below.

1. Two parallel local providers, one is dead code. (resolved)
LocalGitWorkspaceProvider is the only local sandbox provider; the
RepoManagerWorkspaceProvider bridge has been removed. Parsing still
uses RepoManager for its own clone/eviction; sandbox traffic does not.

2. Dual unsynchronized persistence. (resolved for sandbox traffic)
With the bridge gone, sandbox state lives only in JsonSandboxStore.
Parsing's RepoManager metadata at
.repos/.meta/<owner>/<repo>/branch__commit.json is independent and
no longer needs to reconcile.

3. Eviction lives outside the sandbox application layer.
Volume tracking and tiered eviction (worktrees first at 80%, full
repos at 90%) are inside RepoManager. The sandbox module has no
EvictionPolicy port and no eviction logic of its own.

4. Parsing bypasses the sandbox abstraction.
parsing_service.py:298 calls parse_helper.clone_or_copy_repository
which goes directly to RepoManager. There is a feature-flagged
SandboxClient path (SANDBOX_PARSING_ENABLED), but it is not the
default and does not persist a Workspace past the call. After
update_project_status(..., READY) at parsing_service.py:575 no
workspace record exists in the sandbox store.

5. No first-class RepoCache entity. RepoCache is declared in
models.py:115 but Workspace.repo_cache_id is always None. There
is no RepoCacheProvider port; the bare-repo concept is implicit
inside each adapter.

6. WorkspaceMode overloads four concerns: read-only vs writable,
branch creation, sharing, and keying. Branch-creation logic is
duplicated across LocalGitWorkspaceProvider._create_workspace_sync
and daytona/provider.py:_ensure_worktree. Capabilities should be
explicit on the workspace, derived from mode at construction.

7. Daytona adapter leaks SDK types. Any-typed sandbox handles
(_client_factory, _sandboxes) flow through the application layer.
DaytonaRuntimeProvider.exec reaches into sandbox.process.exec
directly. Worktree paths use only branch_name (vs. local's
<user>_<scope>_<branch>), which weakens isolation guarantees.

8. No git-platform port. PR creation is not represented in the
sandbox layer. commit and push exist on SandboxClient, but
creating a PR has to bypass the sandbox abstraction.

9. Tool surface uses contextvars instead of explicit dependencies.
tool_functions._resolve reads user_id from a contextvar and looks
up repo_name via DB. The agent harness sets the contextvar at
pydantic_agent.py:613-621. A toolset factory should take
(client, run_context) explicitly.

10. No eviction port / no per-conversation cleanup hook.
SandboxStore lacks list_workspaces_by_repo,
find_workspaces_for_eviction, etc. EDIT-mode worktrees are only
reaped by RepoManager's age-based eviction; no
release_session(conversation_id) exists.

---

Layered Architecture

text
Agent / Tool layer
    |
    v
SandboxService
    - resolve repo identity
    - get/create repo cache
    - get/create workspace
    - attach/resume runtime
    - enforce locks, TTL, eviction
    |
    +--> RepoCacheStore / WorkspaceStore / RuntimeStore
    |
    +--> RepoCacheManager
    |       local implementation wraps existing RepoManager
    |
    +--> WorkspaceManager
    |       local implementation creates git worktrees
    |
    +--> RuntimeProvider port
            DockerProvider / DaytonaProvider / E2BProvider / LocalReadOnlyProvider

The repo cache and workspace layers own persistence. The runtime provider owns
execution.

---

Public Service API

Tools and agents should call SandboxService, not backend adapters directly.

python
app/modules/sandbox/service.py

from dataclasses import dataclass
from typing import Literal, Optional

WorkspaceMode = Literal["analysis", "edit", "task"]

@dataclass(frozen=True)
class WorkspaceRequest:
    user_id: str
    project_id: str
    repo_name: str                 # "owner/repo"
    repo_url: Optional[str]
    base_ref: str                  # branch or commit
    mode: WorkspaceMode
    conversation_id: Optional[str] = None
    task_id: Optional[str] = None
    branch_name: Optional[str] = None
    create_branch: bool = False

@dataclass(frozen=True)
class RuntimeRequest:
    workspace_id: str
    image: str
    env: dict[str, str]
    writable: bool = True
    network: Literal["none", "limited", "default"] = "limited"
    timeout_s: Optional[int] = None

class SandboxService:
    async def get_or_create_workspace(
        self, request: WorkspaceRequest
    ) -> "Workspace":
        ...
    async def get_or_create_runtime(
        self, request: RuntimeRequest
    ) -> "SandboxRuntime":
        ...
    async def exec(
        self,
        workspace_id: str,
        request: "ExecRequest",
    ) -> "ExecResult":
        ...
    async def hibernate_runtime(self, runtime_id: str) -> None:
        ...
    async def destroy_runtime(self, runtime_id: str) -> None:
        ...
    async def destroy_workspace(self, workspace_id: str) -> None:
        ...

Convenience methods can exist for common tool flows:

python
async def get_or_create_analysis_workspace(user_id, project_id) -> Workspace: ...
async def get_or_create_edit_workspace(user_id, project_id, conversation_id) -> Workspace: ...
async def run_command(workspace_id, command) -> ExecResult: ...

---

Runtime Port

The provider port should be about compute, not repo cloning policy.

text
/ Detailed source-code truncated for AI context efficiency. /

Optional Capabilities

Do not rely on isinstance(provider, SomeProtocol) unless the protocol is
runtime-checkable. Prefer explicit optional capability accessors.

python
@dataclass(frozen=True)
class RuntimeCapabilities:
    snapshot: bool = False
    preview_url: bool = False
    interactive_session: bool = False

class SnapshotCapability(Protocol):
    async def snapshot_runtime(self, runtime_id: RuntimeId, label: str | None = None) -> str: ...
    async def restore_runtime(self, snapshot_id: str) -> SandboxRuntime: ...

class PreviewURLCapability(Protocol):
    async def expose_port(self, runtime_id: RuntimeId, port: int) -> str: ...

class SessionCapability(Protocol):
    async def open_session(self, runtime_id: RuntimeId) -> "Session": ...

Provider construction can expose these as attributes:

python
provider.snapshotter: SnapshotCapability | None
provider.preview_urls: PreviewURLCapability | None
provider.sessions: SessionCapability | None

---

Storage Model

Persist this in Postgres, even if the first implementation only supports local
filesystem paths.

sandbox_repo_caches

One row per durable repo mirror.

Recommended columns:

- id
- repo_name
- repo_url
- provider
- provider_host
- local_path
- auth_scope_hash
- last_fetched_at
- last_used_at
- size_bytes
- state
- created_at
- updated_at

Local implementation can mirror existing .repos/.meta data, then migrate more
fully later.

sandbox_workspaces

One row per durable worktree/workspace.

Recommended columns:

- id
- repo_cache_id
- project_id
- user_id
- mode
- conversation_id
- task_id
- base_ref
- branch_name
- local_path
- state
- dirty
- pinned_until
- last_used_at
- size_bytes
- created_at
- updated_at

Suggested uniqueness:

- Analysis workspace: (user_id, project_id, base_ref, mode) where
mode = "analysis".
- Edit workspace: (user_id, project_id, conversation_id) where
mode = "edit".
- Task workspace: (user_id, project_id, task_id) where mode = "task".

sandbox_runtimes

One row per runtime attachment.

Recommended columns:

- id
- workspace_id
- backend_kind
- backend_runtime_id
- image
- state
- last_started_at
- last_used_at
- expires_at
- created_at
- updated_at

Runtime records can be deleted aggressively. Workspace records should survive
runtime destruction.

---

Workspace Lifecycle

Analysis Flow

Use this for read-only code search and exploration.

1. Resolve project_id to repo details.
2. Ensure repo cache exists using RepoManager.ensure_bare_repo or
prepare_for_parsing.
3. Get or create a clean worktree for the requested branch/commit.
4. Attach a read-only runtime when possible.
5. Run whitelisted read-only commands.

This can continue using bash_command plus gvisor_runner.py initially, but
the tool should treat gVisor fallback as reduced isolation and keep commands
read-only.

Edit Flow

Use this for feature work, bug fixes, tests, and PR creation.

1. Resolve project_id to repo details.
2. Ensure repo cache exists.
3. Create or reuse an edit workspace keyed by conversation_id.
4. Create branch agent/edits-{conversation_id} from the project base branch.
5. Attach a write-capable runtime with the workspace mounted writable.
6. Run commands and edits inside that runtime.
7. Commit/push/PR from the same workspace.

This should replace the current split where generated changes live in Redis and
then get applied to the worktree. Redis can remain a UI/change-tracking cache,
but the workspace should become the source of truth for actual files.

Task Flow

Use this for multi-agent or background work where one conversation may spawn
multiple independent implementation attempts.

1. Key workspace by task_id.
2. Create branch agent/task-{task_id} or a child branch from the edit branch.
3. Keep each task workspace isolated.
4. Merge/cherry-pick/diff back into the conversation edit workspace if accepted.

---

Eviction Policy

Eviction should be tiered. Compute is cheap to recreate; repo clones are
expensive.

Runtime Eviction

Default behavior:

- Stop idle runtimes after 15-30 minutes.
- Destroy stopped runtimes after 1-6 hours.
- Never delete the workspace as part of runtime eviction.

Triggers:

- Idle timeout.
- Backend quota pressure.
- Explicit user/project cleanup.
- Failed runtime health checks.

Workspace Eviction

Default behavior:

- Keep edit workspaces for longer than runtimes, for example 7-30 days.
- Keep dirty or recently active workspaces longer.
- Never evict pinned workspaces.
- Prefer evicting clean analysis workspaces before dirty edit workspaces.

Suggested priority:

1. Clean analysis workspaces older than TTL.
2. Clean task workspaces older than TTL.
3. Clean edit workspaces older than TTL.
4. Dirty unpinned task workspaces under disk pressure.
5. Dirty unpinned edit workspaces only under severe disk pressure.

Before deleting a dirty workspace, consider one of:

- Create a patch artifact.
- Commit to an internal branch.
- Mark it as eviction_blocked and alert/admin-log.

Repo Cache Eviction

Default behavior:

- Keep repo caches longest.
- Evict only when disk pressure remains after runtime and workspace eviction.
- Use LRU with size awareness.
- Do not evict a repo cache with active workspaces.

The existing RepoManager already has tiered eviction hooks:

- Worktree threshold: _WORKTREE_EVICTION_THRESHOLD_PERCENTAGE
- Repo threshold: _REPO_EVICTION_TARGET_PERCENTAGE
- Stale worktree age: _STALE_WORKTREE_MAX_AGE_DAYS

The sandbox service should reuse this behavior first, then move metadata into
Postgres when needed.

---

Concurrency and Locking

Concurrency needs to be explicit because git worktrees and package managers are
not safe under arbitrary parallel mutation.

Use DB uniqueness plus advisory locks:

- Lock repo cache creation by normalized repo identity.
- Lock workspace creation by workspace uniqueness key.
- Lock mutating commands per workspace.
- Allow concurrent read-only commands when no mutating command is running.

Command classes:

- read: rg, grep, cat, ls, static inspection.
- write: file edits, git checkout, git add, git commit, formatters.
- install: package manager commands, dependency resolution.
- test: usually read-mostly but often writes build artifacts; treat as
mutating unless mounted with a separate cache/output directory.

For the first implementation, a conservative per-workspace async lock around
all write-capable runtime commands is acceptable.

---

Security Rules

- Do not pass host environment variables into runtimes by default.
- Inject only scoped credentials that the command actually needs.
- Keep git credentials out of remotes after clone/fetch.
- Do not mount host repo paths broadly; mount only the selected workspace.
- For write-capable work, do not silently fall back to host subprocess.
- Default network to limited or none; allow broader network only for
explicit workflows like dependency install.
- Validate all file paths against the workspace root.
- Treat user-provided repo names, branches, and paths as untrusted input.

Important local-mode rule:

gvisor_runner.py is acceptable for the existing read-only analysis path. It
should not be used as the write-capable sandbox runtime because it mounts
read-only and has regular-subprocess fallback behavior.

---

Adapter Responsibilities

| Adapter | Runtime backing | Workspace persistence | Good first use | Notes |
| --- | --- | --- | --- | --- |
| LocalReadOnlyProvider | existing gVisor runner | local worktree | read-only analysis | No write workflows; no silent trust in fallback |
| DockerProvider | long-lived container | local worktree or Docker volume | first write-capable backend | Best first implementation target |
| DaytonaProvider | Daytona workspace/runtime | native or synced workspace | managed sandbox backend | Use native snapshots/previews when useful |
| E2BProvider | Firecracker microVM | native or synced workspace | fast ephemeral runtime | Validate persistence semantics carefully |

Local Daytona development notes:

- One-shot setup: app/src/sandbox/scripts/setup-daytona-local.sh brings the
Daytona compose stack up. The script layers
scripts/daytona-overrides/docker-compose.override.yaml on top of the
upstream compose so the dashboard host port is 3010 by default (port
3000 is reserved for the potpie frontend); the override also mounts a dex
config that whitelists http://localhost:3010 as an OIDC redirect URI.
Set DAYTONA_DASHBOARD_PORT=... before running the script to remap to
another port.

After the stack starts the script waits for /api/health, mints a dev API key for
the bundled [email protected] / password user, sets a default region if
needed, writes app/src/sandbox/.env.daytona.local, and prints the URL of
every observability dashboard the compose file already ships:
- Daytona dashboard: http://localhost:3010
- Sandbox snapshots: http://localhost:3010/dashboard/snapshots
- Active sandboxes: http://localhost:3010/dashboard/sandboxes
- Swagger API: http://localhost:3010/api
- Jaeger traces: http://localhost:16686
- pgAdmin: http://localhost:5050
- Container registry UI: http://localhost:5100
- MinIO console: http://localhost:9001 (minioadmin / minioadmin)
- MailDev: http://localhost:1080
- Uses the Daytona compose stack vendored in-repo at
app/src/sandbox/daytona/ by default (no external clone needed). To build
Daytona images from source instead, point at a clone with
DAYTONA_REPO_PATH=/path/to/daytona.
- Do not pass --project-directory to docker compose. Volume binds in the
Daytona compose file are relative to the compose file's own directory and
silently auto-create stub directories at the wrong location otherwise.
- Cleanup: app/src/sandbox/scripts/teardown-daytona-local.sh deletes only
sandboxes labelled managed-by=potpie. Pass --stack to also bring the
compose stack down with -v.
- The bundled daytonaio/sandbox:0.5.0-slim snapshot does not ship the
git CLI. The Daytona adapter handles this by using the toolbox git.clone
/ git.create_branch / git.checkout_branch endpoints and verifying
outcomes by reading .git/HEAD directly (the toolbox SDK occasionally
raises DaytonaValidationError("...: ") on operations that actually
succeeded).
- Tests resolve proxy.localhost to 127.0.0.1 in-process (see
tests/e2e/conftest.py) so neither sudo nor the setup-proxy-dns.sh
dnsmasq script is required for E2E runs. Long-lived shell access still
needs the dnsmasq setup or an /etc/hosts entry.
- Adapter env vars (sourced from .env.daytona.local):
SANDBOX_WORKSPACE_PROVIDER=daytona, SANDBOX_RUNTIME_PROVIDER=daytona,
DAYTONA_API_URL, DAYTONA_API_KEY, optional DAYTONA_SNAPSHOT,
DAYTONA_WORKSPACE_ROOT.

The adapter must:

- Translate runtime lifecycle and exec calls.
- Map backend errors into typed sandbox errors.
- Enforce its declared mount/network behavior.
- Report capabilities truthfully.

The adapter must not:

- Decide which user/repo/workspace should be used.
- Own the clone-on-create policy.
- Reach into Postgres workspace mappings directly.

---

Typed Errors

Every adapter should map backend-specific failures into a small error set.

python
class SandboxError(Exception): ...
class SandboxNotFound(SandboxError): ...
class SandboxUnauthorized(SandboxError): ...
class SandboxTimeout(SandboxError): ...
class SandboxConflict(SandboxError): ...
class SandboxUnavailable(SandboxError): ...
class SandboxResourceLimit(SandboxError): ...
class SandboxCommandRejected(SandboxError): ...

Service-level repo/workspace errors should be separate:

python
class WorkspaceError(Exception): ...
class WorkspaceNotFound(WorkspaceError): ...
class WorkspaceLocked(WorkspaceError): ...
class WorkspaceDirty(WorkspaceError): ...
class RepoCacheUnavailable(WorkspaceError): ...
class RepoAuthFailed(WorkspaceError): ...

---

Implementation Roadmap

The original Phase 1-5 plan is complete — the sandbox module, the
runtime port, the Daytona adapter, the agent tool surface, and the
Postgres-ready store are all shipped. The post-revamp phases (P1-P8)
each address a numbered gap from the audit. Status as of this
session:

P1 — Unify the local provider — DONE

Closes gaps 1, 2, 3.

* EvictionPolicy port at domain/ports/eviction.py with
EvictionResult value type; NoOpEvictionPolicy default in
adapters/outbound/memory/eviction.py.
* LocalGitWorkspaceProvider accepts eviction= kwarg, calls
evict_if_needed on cache miss.
* LocalGitWorkspaceProvider is now the only local provider. The
RepoManagerWorkspaceProvider bridge and the
SANDBOX_USE_CANONICAL_LOCAL flag have been removed; sandbox traffic
goes through the canonical adapter unconditionally.
* Operator note: any on-disk worktrees created by the old bridge
(layout: <branch> for shared, <user>_<unique>_<branch> for
conversation-scoped) are not visible to the canonical adapter. New
conversations get fresh worktrees in the <user>_<scope>_<branch>
layout; commit/push any in-flight bridge worktree state before
upgrading.
* Volume-aware policy (VolumeBasedEvictionPolicy) replacing the
NoOp default is still a P1 follow-up; the canonical path runs
unbounded until the policy is wired.

P2 — Promote RepoCache to first-class — DONE

Closes gap 5.

* RepoCacheRequest and RepoCache (with stable key) in
domain/models.py.
* RepoCacheProvider port at domain/ports/repos.py.
* RepoCacheStore mixin on SandboxStore; both InMemorySandboxStore
and JsonSandboxStore implement it (rows survive restart).
* LocalRepoCacheProvider at
adapters/outbound/local/repo_cache.py owns bare-repo creation;
LocalGitWorkspaceProvider depends on the cache port and sets
Workspace.repo_cache_id on every workspace it builds.
* SandboxService.ensure_repo_cache(request) keys by repo identity,
takes a per-key lock, persists the row.

P3 — Capabilities split and acquire_session API — DONE

Closes gaps 6 and 10.

* Capabilities(writable, isolated, persistent) value object;
Capabilities.from_mode is the single source of truth.
* Workspace.capabilities populated by every adapter (local, bridge,
Daytona). Round-trips through JsonSandboxStore.
* SandboxService.acquire_session(request) orchestrates ensure-cache
+ workspace creation atomically.
SandboxService.release_session(workspace_id, , destroy_runtime)
hibernates the runtime by default; workspace survives.
* SandboxClient.acquire_session / release_session symmetric public
API.

P4 — Daytona hardening — partial

Addresses gap 7 (correctness portion).

Done:
* _validate_ref in daytona/provider.py rejects newlines / .. in
base_ref and branch_name before they hit shell-style exec calls
(parity with the local adapter).
* Worktree path now <user>_<scope>_<branch> so two conversations on
the same branch get distinct worktrees (no silent collision).

Deferred (code-quality follow-up): The Daytona SDK still types as
Any on _client_factory/_sandboxes; the full DaytonaApi Protocol
abstraction is a 500+ line refactor that doesn't fix any correctness
issue. Track as a P4.5 cleanup.

P5 — Provision-on-parse — DONE

Closes gap 4.

* SandboxClient.ensure_repo_cache(...) thin wrapper over the service.
* provision_repo_cache helper at
app/modules/intelligence/tools/sandbox/client.py.
* parsing_service.py calls _provision_repo_cache_safe from BOTH
READY transitions (eager-return short-circuit and the normal
post-analyze_directory exit). Failures are logged and swallowed —
cache provisioning is an optimization, not a parsing prerequisite.

P6 — Tool surface refactor — DONE

Closes gap 9.

* create_sandbox_tools(client=..., handle=...) — explicit-handle
factory mode. Tools dispatch through pre-bound (client, handle)
closures with input schemas that omit project_id. Capability
gating drops write tools when the handle is read-only
(enforce_capabilities=True default).
* The legacy zero-arg create_sandbox_tools() form keeps working —
required for back-compat with the existing harness wiring at
multi_agent/agent_factory.py and pydantic_agent.py.
* Helper functions extracted in tool_functions.py:
_exec_text_editor, _exec_shell, _exec_search, _exec_git,
_exec_pull_request. Both factory modes funnel through the same
helpers.
* WorkspaceHandle.capabilities carries the gating signal.
* Contextvar machinery in tools/sandbox/context.py is kept for
the legacy form — full removal happens once harness callers migrate
to the explicit form (P6.5 cleanup).

P7 — GitPlatformProvider and PR tool — DONE

Closes gap 8.

* GitPlatformProvider port at domain/ports/git_platform.py;
PullRequestRequest / PullRequest value objects in
domain/models.py; PullRequestFailed /
GitPlatformNotConfigured errors.
* GitHubGitPlatformProvider bridge adapter at
app/modules/sandbox_repos/git_platform.py wraps the existing
code_provider.github.GitHubProvider so auth chain stays put.
* SandboxService.create_pull_request(request) enforces "platform
configured" precondition; SandboxClient.create_pull_request(handle,
...) enforces "writable workspace" precondition.
* sandbox_pr agent tool — included in the explicit toolset only when
the harness passes `pr_repo_name=...; capability-gated on
writable handles. Push the branch via sandbox_git push first; the
PR tool is the platform-side step only.
* Production wiring of the platform provider is a follow-up. The
per-call user resolution (auth tokens scoped to the calling user)
doesn't fit the process-wide SandboxClient cleanly; needs a small
request-scoped factory before it can run in prod.

P8 — Postgres store and multi-worker locks — DEFERRED

Closes the implicit single-node assumption in JsonSandboxStore and
InMemoryLockManager. The schema sketch is already documented above
(sandbox_repo_caches, sandbox_workspaces, sandbox_runtimes).
Implementation requires a Postgres connection and migration tooling
that aren't in this session's scope. Adapter signatures will mirror
the existing in-memory and JSON ones, so the swap is a bootstrap-only
change.

Track as a follow-up. The current JsonSandboxStore is suitable
for single-node deployments; multi-worker / multi-host setups need the
Postgres adapter, since the JSON store's flush model assumes a single
writer.

Outstanding follow-ups (small)

* P1 follow-up — VolumeBasedEvictionPolicy reading from
SandboxStore so canonical-local has bounded disk use.
* P4 follow-up — DaytonaApi Protocol port to remove Any typing.
* P6 follow-up — migrate harness callers
(multi_agent/agent_factory.py, pydantic_agent.py) to the
explicit-handle form, then delete the contextvar plumbing.
* P7 follow-up — request-scoped GitPlatformProvider factory so the
per-user auth chain works in production.
* P8 — Postgres adapters once the DB story lands.

---

Open Questions

- Should edit workspace persistence be keyed by conversation_id, by an
explicit "agent task/session id", or both?
- When a dirty workspace is old enough to evict, should Potpie auto-commit to
an internal branch, save a patch artifact, or block eviction?
- Should dependency caches be per-user, per-repo, or per-workspace?
- How much network access should test/install commands get by default?
- Should local Docker workspaces mount host worktrees directly, or should they
copy/sync into a Docker volume for stronger host isolation?

---

Sandbox Integration Plan

Sandbox Integration Plan

This document plans the next phase of app/src/sandbox: turning it into the
single library that everything else in potpie uses to materialize repos and run
code, and retiring the app/modules/repo_manager + app/modules/intelligence/
tools/code_changes_manager stack.

It is a plan, not a spec. Where there are real tradeoffs the doc names them
and points at the surfaces involved, but leaves the call to the implementer.
Read docs/sandbox-core-setup.md first — this builds on the model defined
there (RepoCache / Workspace / Runtime).

---

1. Where we are

The sandbox module today (app/src/sandbox/sandbox/) is hexagonal and runnable:

- Domain: Workspace, Runtime, RepoIdentity, WorkspaceRequest,
ExecRequest, etc. (domain/models.py).
- Ports: WorkspaceProvider, RuntimeProvider, SandboxStore, LockManager
(domain/ports/*).
- Adapters: local-git workspace, local-subprocess runtime, docker runtime,
daytona workspace + runtime, file/json store, in-memory locks
(adapters/outbound/*).
- Application service: SandboxService (application/services/sandbox_service.py)
exposes get_or_create_workspace, get_or_create_runtime, exec,
hibernate_runtime, destroy_runtime, destroy_workspace. It is
idempotent, locks per-workspace, and tracks dirty after writes.
- E2E tests cover all three runtime backends end-to-end (subprocess, docker,
daytona). Daytona dev stack is bootstrapped via scripts/setup-daytona-local.sh
and the override compose file.

The rest of potpie still drives a parallel stack:

- app/modules/repo_manager/ — bare repo + worktree management on disk under
.repos/<owner>/<repo>/. Has its own auth chain, eviction, metadata.
- app/modules/intelligence/tools/code_changes_manager/ — Redis-backed
per-conversation file-edit staging area, with ~20 LangChain
StructuredTools wrapped around it (add_file_to_changes,
update_file_lines, replace_in_file, …, plus git_commit, git_push,
bash_command).
- Parsing (app/modules/parsing/) calls RepoManager.prepare_for_parsing() to
get a worktree path and walks it directly with os.walk/Tree-sitter.
- Agents (PydanticAI in app/modules/intelligence/agents/) get tools via
ToolService + ToolResolver, with ChatContext (project_id, user_id,
conversation_id, branch, local_mode) carrying scope.

The two stacks duplicate concepts: both clone, both manage worktrees, both
think about branches. The plan unifies them under the sandbox module.

---

2. Goals

- A small, library-shaped public API on app/src/sandbox that the rest of
potpie can import and use to: get a sandbox, get a working tree on a branch,
read/write files, run commands, search, commit, push.
- Repo lifecycle owned by sandbox. The caller passes
(repo, branch, user, project) — sandbox does the cloning, the worktree
creation, the branch switching, and (eventually) the eviction. Parsing and
agents both go through it.
- Pre-provisioned tooling. Common dev tools (rg, git, fd, jq,
python, node) are present in the runtime out of the box, so agent tools
don't need to detect/install at runtime.
- One backend sandbox, many branches. A single backend container per
(user, project) hosts multiple worktrees so multiple agent runs on
different branches share the same expensive thing (the Daytona sandbox /
Docker container) without serializing.
- Sandbox-backed agent tools ship from the sandbox library itself,
registered into ToolService like any other tool. Each tool resolves its
workspace from the agent's run context.
- CodeChangesManager is gone. Edits go straight to the worktree (which
is durable git state). The Redis-staged-changes model is replaced by
"edit the file, commit when done." If we want stage-and-review semantics
later they live above the sandbox, not inside it.
- .repos becomes one adapter under the sandbox WorkspaceProvider
port, used for local development and tests. Daytona is the production path.

Non-goals

- Replacing the agent framework, the LLM provider abstraction, or the search
service. The sandbox owns "where the bits live" — not "how the agent
thinks."
- Full distributed locking. The InMemoryLockManager is fine for the single-
worker case; a Redis-backed lock manager is a separable later concern.
- Snapshot-based hibernation as a primary persistence mechanism. Git worktrees
+ the backend's volume are the persistence.
- Backwards compatibility with the code_changes_manager Redis schema. We are
removing it; there's no migration.

---

3. Conceptual additions

The current sandbox model (one Workspace = one branch) is right for what it
solves, but the integration goals push two extensions:

3.1 RepoCache becomes load-bearing

RepoCache exists in domain/models.py (lines 116–127) but isn't wired in.
The plan promotes it to a real concept owned by the workspace provider:

- RepoCache = "the bare clone, somewhere a backend can reach it."
- Workspace = "a working tree on top of a RepoCache, scoped to a branch."
- One RepoCache per (user, repo) — or per (repo) if we trust shared
cache semantics; defer that call until we actually share across users.
- Many Workspace per RepoCache, one per active branch.

In adapter terms:

| Backend | RepoCache materialization | Workspace materialization |
| ---------------- | ------------------------------------------- | -------------------------------------- |
| Local git | .repos/<owner>/<repo>/.bare/ | .repos/.../worktrees/<key>/ |
| Daytona | Bare clone inside a long-lived sandbox | Worktree in the same sandbox |
| Docker | Bare clone in a named docker volume | Worktree mounted into the runtime |

The Daytona row is the interesting one: today each WorkspaceRequest creates
its own Daytona sandbox. The new model creates one Daytona sandbox per
(user, project) and uses git worktree inside it for each branch. That's
how we get multi-branch concurrency without paying for N sandboxes.

The implementer should decide whether to:
- (a) Add a RepoCacheProvider port alongside WorkspaceProvider, or
- (b) Fold the cache semantics into WorkspaceProvider (one provider, two
conceptual layers), or
- (c) Keep RepoCache purely as a value object that providers populate
internally.

(b) or (c) is probably right — adding a port costs more than it pays for
unless we expect to swap cache backends independently.

3.2 Workspace as a branch handle

A Workspace already has metadata["branch"] and a worktree path. The plan
keeps that, but tightens the lifecycle:

- Creation: clone or fetch into the cache, then git worktree add for the
branch.
- Switch-branch: not actually a switch — it's "give me a different
Workspace on the same RepoCache." The caller asks for a workspace by
(user, project, branch) and gets the right worktree.
- Reuse: the existing key-based idempotency in SandboxService.get_or_create_
workspace already does this (line 50). Verify the key formula handles the
(repo, branch) case cleanly without conversation_id or task_id
required.
- Cleanup: destroy_workspace removes the worktree but keeps the cache.
A separate path destroys the cache (or the whole backend container).

This is the biggest behavioral change. Today the daytona adapter
(adapters/outbound/daytona/provider.py:131-152) calls
daytona.create(...) per workspace. After the change, sandbox creation is
keyed on (user, project) and worktree creation runs inside an existing
sandbox.

---

4. The public client API

What the rest of potpie should be able to import. Treat names as suggestions.

4.1 The package surface

text
app/src/sandbox/sandbox/__init__.py
    # The library export
    SandboxClient
    SandboxClientConfig
    # Re-exports of the small set of types callers actually need:
    WorkspaceHandle, ExecResult, NetworkMode, CommandKind,
    SandboxError, WorkspaceNotFound, ...

SandboxClient is a thin façade over SandboxService plus the bootstrap
container. The intent: callers don't construct providers, stores, locks, or
build runtime specs by hand. They get a client and ask for what they need.

Sketch — flesh out in code:

text
/ Detailed source-code truncated for AI context efficiency. /

4.2 What WorkspaceHandle is

A small, opaque object containing the IDs the client needs to talk to the
service: workspace_id, the resolved branch, the runtime working dir.
Not the Workspace domain object — the handle is the stable thing returned
to callers. Internally the client looks up the live Workspace each call.

Why opaque: it lets the implementer change what's stored (a single ID vs a
small struct vs a Workspace snapshot) without churning every caller.

4.3 Read/write helpers vs exec

The existing exec() is enough to do everything, but agent tools end up
shelling out for trivial operations and re-implementing argument quoting.
The helpers (read_file, write_file, list_dir, search) are first-class
on the client because:

- They have a fixed surface that's easy to mock / fake in tests.
- They can dispatch to backend-native APIs when available (Daytona toolbox
has fs.upload_file, fs.download_file, git.* — currently only used by
the daytona workspace provider).
- They give the agent prompt a small, named tool surface (see §7).

The implementer should look at Daytona's toolbox API
(adapters/outbound/daytona/provider.py, lines 154–228 are precedent) and
wire the helpers through RuntimeProvider so each backend has one chance
to do it natively before falling back to exec.

4.4 What we deliberately don't expose (yet)

- No Runtime lifecycle on the client. Runtime is implicit; exec brings
it up. hibernate / destroy show up as release_workspace.
- No streaming exec. exec_stream exists in the port but the inbound
surface stays sync-result for v1; revisit when an agent flow actually
benefits.
- No "preview URL" / port-forwarding. RuntimeCapabilities already models
this; expose it when there's a caller.

---

5. Preinstalled tooling

Today the runtime images are minimal: python:3.12-slim for docker default,
daytonaio/sandbox:0.5.0-slim for daytona, host PATH for subprocess.
Nothing has rg (ripgrep), and the Daytona slim image doesn't even ship git
CLI — the daytona adapter explicitly works around that with the toolbox API
(see provider.py:182-185).

The plan: ship our own image for the docker and daytona backends with a
known-good toolset.

5.1 Image contents (proposal)

A single Dockerfile in app/src/sandbox/images/agent-sandbox/ produces
potpie/agent-sandbox:<version>:

- Base: python:3.12-slim (or debian:stable-slim if startup time is an
issue and we want a cheaper base).
- Tools: git, git-lfs, ripgrep, fd-find, jq, curl, ca-certificates,
tini, tree, less, coreutils, procps, openssh-client.
- Runtimes: Python (with pip, uv optional), Node LTS, GitHub CLI (gh)
if we want it for PR creation.
- A non-root user agent with $HOME persistent — the worktree will live
under /home/agent/work/.
- An entrypoint that pre-creates the worktrees dir and exec's the requested
command (mirrors what the override compose entrypoint does today).

The implementer should check the actual size — going from slim+toolbox to
full-fat is a real tradeoff for Daytona cold-start. If that's painful, split:
a "lean" image without Node and a "full" image with everything; pick per
workload.

5.2 Daytona snapshot

Daytona consumes images via "snapshots." The override compose stack already
has a flow for this (scripts/setup-daytona-local.sh). Process:

1. Build the image.
2. Push to a registry Daytona can pull from. (For dev: the local docker daemon.)
3. Run daytona snapshot create potpie/agent-sandbox:<version>
(or however the Daytona SDK phrases it — check existing scripts).
4. Default DAYTONA_SNAPSHOT env var to the new snapshot in .env.daytona.local
and in bootstrap/settings.py.

Tests: extend tests/e2e/test_daytona_e2e.py with a sanity check that
rg --version and git --version succeed inside a fresh sandbox.

5.3 Subprocess backend

The local subprocess backend is purely for tests and dev-machine debugging.
It uses host PATH. We don't ship anything; we document that rg should be
on PATH. Tests already skip when not available.

---

6. Repo lifecycle in the new model

6.1 Parsing path

Today ParseHelper.clone_or_copy_repository (app/modules/parsing/)
calls RepoManager.prepare_for_parsing and walks the resulting path with
os.walk. Tomorrow:

text
ParsingService.parse_directory(repo_details, ...)
  → SandboxClient.get_workspace(
        user_id, project_id, repo, branch=base_ref,
        mode=WorkspaceMode.ANALYSIS, create_branch=False,
    )
  → handle = ...
  → run parsing against handle (see below)
  → SandboxClient.release_workspace(handle)   # or keep for re-parse

How parsing actually reads files matters:

- Option A (recommended, easier): parsing keeps running on the host;
the sandbox client just produces a host-readable path. For the local-fs
backend this is the existing .repos/.../worktrees/.... For Daytona,
this means: don't run parsing in Daytona — run the cheap clone in
Daytona only when the agent actually needs a sandbox, and use the
local-fs backend for parsing. Two backends, one client API, picked per
workload.

- Option B (harder): parsing runs inside the sandbox (rust extractor
baked into the image, results streamed back). The agent (Map parsing
flow & repo dependency writeup, §10) flagged GitPython fork-safety,
Rust backend distribution, and embedding model size as the costs. Worth
doing if we want a uniform model for managed-cloud customers, but not
the v1.

Pick A. Make sure the client's helpers don't accidentally tie callers to
"the path is on the host." The WorkspaceHandle should expose a
local_path: str | None field that is populated only for local-fs backends
and None for daytona — parsing checks for it and skips Daytona for now,
or refuses with a clear error.

6.2 Agent path

Today: agent tool fires, calls RepoManager to get a worktree, writes
through CodeChangesManager to Redis, later commits.
Tomorrow:

text
ChatContext { project_id, user_id, conversation_id, branch, ... }
  → SandboxClient.get_workspace(
        user_id, project_id, repo, branch=branch,
        mode=WorkspaceMode.EDIT, create_branch=True,
    )
  → handle is cached on the agent run (see §7.3 for where)
  → tools call client.{read_file, write_file, search, exec, commit, ...}
  → run ends → release_workspace (don't destroy the worktree yet — keep it
    until conversation cleanup).

The branch model: WorkspaceMode.EDIT already names branches
agent/edits-{conversation_id} (adapters/outbound/local/git_workspace.py,
lines 204-211). Keep that. For the daytona backend the branch lives as a
worktree on a shared sandbox per (user, project).

6.3 Switching branches

User asked for "checkout somehow when plugging to the agent." Two
interpretations:

- (a) Same conversation, switch branch — operator wants to abandon the
current branch and resume on another. Express as: release the old
workspace, get a new workspace with a different branch.

- (b) Same backend container, multiple branches in flight — multiple
conversations / agents, one Daytona sandbox. Express as: each
get_workspace returns a new worktree inside the existing sandbox.

(b) is the real concurrency story; (a) is a special case of "release +
get_or_create." The implementer shouldn't add a switch_branch operation
on the client — it's just two existing calls.

6.4 Cleanup

Three layers:

1. Worktree (cheap): destroy on conversation close, or after N days idle.
2. Backend sandbox (expensive in $$$): destroy on user inactivity, or per
organization quota. Hibernate (Daytona auto-stops after 30s; auto-archives
after 12h — already configured in
adapters/outbound/daytona/provider.py:142).
3. Repo cache (expensive in disk): LRU evict, or per-repo TTL.

Today's RepoManager._evict_if_needed (the writeup §3 in the
code-changes-manager map) is a reasonable starting point. Port it as a
background task that the local-fs adapter runs, not as inline-during-
clone behavior — that surprised people. Daytona handles its own GC for
sandboxes; we only need to run cache cleanup if we end up storing caches
in named volumes.

---

7. Agent tool exports

The user wants a set of tools they can plug into agents that gives the
agent access to a specific (repo, branch) sandbox.

7.1 Tool catalog (proposal)

Ship a small, opinionated set. Names are starting points — match the
existing tool naming style (snake_case, verbs). Each tool's input schema
includes project_id (the agent already passes this) and the input gets
resolved to a WorkspaceHandle at call time.

| Tool | Wraps | Agent uses for |
| -------------------------- | ------------------------------------------- | ----------------------------------- |
| sandbox_read_file | client.read_file | view a file (line numbers optional) |
| sandbox_write_file | client.write_file | full-file replace |
| sandbox_str_replace | client.read_file + write | targeted in-file edit |
| sandbox_list_dir | client.list_dir | navigate |
| sandbox_search | client.search (ripgrep) | grep across the tree |
| sandbox_run | client.exec | run any command (whitelisted?) |
| sandbox_run_tests | client.exec + framework detection | language-aware test runner |
| sandbox_git_status | client.status | what changed |
| sandbox_git_diff | client.diff | review changes |
| sandbox_git_commit | client.commit | commit |
| sandbox_git_push | client.push | push (auth-token aware) |
| sandbox_open_pr | provider-specific PR creation | end of feature flow |

The implementer should compare to today's code_changes_manager tools
(20-ish tools across staging operations) and consciously drop the ones
that exist only because edits were staged in Redis — clear_file,
get_changes_summary, serialize, revert_file, etc. The agent operates
directly on the worktree; Git is the source of truth and the audit log.

7.2 Where the tool code lives

Two reasonable placements:

- Inside the sandbox library, exported as factory functions. Tools
import only from the public client API. This is cleanest — the sandbox
library is self-contained.
- In app/modules/intelligence/tools/sandbox/, depending only on
the sandbox client. This matches the rest of the tool layout.

Pick the second. Sandbox stays a pure library; potpie-specific glue
(StructuredTool wrapping, ToolService registration, ChatContext binding)
stays where the rest of that glue lives. The library only exports
data-shaped helpers, not LangChain StructuredTools.

7.3 How tools resolve the workspace

The tool needs to know (user_id, project_id, repo, branch) to call
client.get_workspace. Today ChatContext already carries all four
(app/modules/intelligence/agents/chat_agent.py:71-162). Two viable
approaches:

- Closure capture: ToolService.__init__ (or a new
SandboxToolFactory) constructs each tool with the live ChatContext
for the run. Tools don't take project_id in their args. Pros: agent
can't "lie" about which project. Cons: tool factories need to be
re-instantiated per agent run, which doesn't match the current
ToolService lifecycle (per-user singleton).

- Explicit args: tool input schema keeps project_id (matching all
current tools — see code_query_tools/bash_command_tool.py:455-525).
The tool resolves it on each call. The branch is discovered server-side
from ChatContext rather than the LLM picking. Pros: fits the
existing pattern. Cons: agent could in theory pass a different
project_id, but ProjectService.get_project_from_db_by_id_sync already
validates user-project ownership.

Pick explicit args for parity. Branch comes from ChatContext via a
mechanism the implementer can mirror from bash_command_tool (which uses
get_or_create_edits_worktree_path and relies on the conversation context).
For sandbox tools, that translates to: a small SandboxRunContext
contextvar set at the top of every agent run with the resolved
WorkspaceHandle (or the data needed to fetch it), and tools read it.

7.4 Result shape

Match the existing tools' shape: Dict[str, Any] with success, the
result data, and explicit truncation flags. bash_command_tool's 80k-char
output limit is a precedent — keep similar for sandbox_run. For
sandbox_search return a list of hits with file:line:snippet; that's
what the LLM actually wants.

7.5 Allow-list and registry

Add a sandbox tool group in
app/modules/intelligence/tools/registry/definitions.py and update the
agent allow-lists (code_gen, execute, qna etc. — see
agents/chat_agents/system_agents/). The registry-driven path
(ToolResolver.get_tools_for_agent) is the preferred entry point;
hardcoded allow-lists should be migrated as part of this same change
since they refer to soon-to-be-removed tool names.

---

8. Concurrency model

The combined goal — multiple agents on different branches — needs three
things to be true:

1. One backend container per (user, project), shared across
conversations. Lock key for "create or attach": repo-cache:{user_id}:
{project_id} (or whatever RepoCache.key() ends up being). Held only
for the create critical section.

2. Per-worktree write isolation. Today's lock key
workspace-command:{workspace_id} is right (
application/services/sandbox_service.py:91-96) — keep it. Two agents
on two branches don't share a lock; two agents *in the same
conversation* serialize.

3. No process-wide singletons. SandboxClient is per-(potpie process)
and stateless except for the underlying provider/store/locks. Multiple
Celery workers each hold their own client; they coordinate through the
store (which becomes interesting — see below).

8.1 Store: in-memory vs durable

InMemorySandboxStore and JsonSandboxStore work fine for one process.
Multiple Celery workers need something durable + concurrent: a Postgres
table is the path of least resistance (we already have the DB session).
Add a PostgresSandboxStore adapter; use the same SandboxStore port
unchanged. The implementer should look at the existing context-graph pot
migrations (the recent 20260407_* migration) for precedent on how
sandbox-related schema gets shipped.

8.2 Locks: in-memory vs Redis

Same shape. InMemoryLockManager is fine for tests and single-worker.
Production wants RedisLockManager (we have Redis; the
code_changes_manager's storage layer already uses it). Same LockManager
port — drop in.

The implementer should not block the v1 plan on these; ship the Postgres
store + Redis lock as a follow-up if a single-worker rollout is enough
for the first migration step.

8.3 Cancellation

ChatContext.check_cancelled is the current escape hatch. Sandbox tools
that call long-running exec should poll it (or pass a timeout that
respects it). SandboxClient.exec should accept an optional
cancellation_token callable.

---

9. Migration: removing CodeChangesManager and .repos glue

The two systems are intertwined. Order:

1. Stand up the new client surface. Build SandboxClient over the
existing service, helpers and all. Local-fs backend is enough.
2. Build the new sandbox tools (§7) and register them under their own
names. Don't delete the old tools yet.
3. Move parsing. ParseHelper.clone_or_copy_repository is the only
place outside agents that touches RepoManager. Replace its
RepoManager calls with SandboxClient.get_workspace (using the
local-fs backend, ANALYSIS mode). Tests in
app/modules/parsing/tests/ should still pass.
4. Migrate one agent end-to-end — start with code_gen_agent since
it's the most-touched. Replace its hardcoded tool list with the new
sandbox tool names; update its system prompt. Run the existing
end-to-end smoke tests.
5. Delete CodeChangesManager. Once code_gen_agent is on the new
tools, the staging tools (add_file_to_changes, update_file_lines,
replace_in_file, etc.) have no callers. Delete the package, the
Redis schema, the _init_code_changes_manager plumbing in
execution_flows.py, and the imports that scatter from there.
6. Make .repos an adapter. At this point RepoManager still exists
as an implementation detail of the local-fs WorkspaceProvider.
Refactor: move the bare-repo + worktree code from
app/modules/repo_manager/ into
app/src/sandbox/sandbox/adapters/outbound/local/repo_cache.py
(or similar), keeping the auth chain (sync_helper.py's GitHub App →
OAuth → env-token logic) since it's hard-won. The shape of
LocalGitWorkspaceProvider doesn't change much — it just absorbs
RepoManager's functionality.
7. Delete app/modules/repo_manager/. The legacy module's only job
was to be that adapter; now the sandbox owns it.

Each step ships independently. Steps 1–4 are additive; 5–7 are deletions.
Don't intermix.

9.1 What to do with the staging idea

CodeChangesManager had a useful property: edits were reviewable before
commit. Without it, agent edits land directly in a worktree branch. That's
also reviewable (it's a git branch you can diff against base), and
arguably better — diffing a branch is a tool the LLM and humans both
already understand.

If we miss "show the user a pending-changes summary," that's a UI concern
on top of git diff, not a sandbox concern. Don't put it back in.

9.2 Apply-changes flow

Current flow: apply_changes tool reads from CodeChangesManager Redis
and writes files into the worktree. New flow: there is no apply_changes
— each sandbox_write_file / sandbox_str_replace writes directly. The
git_commit tool (which is now sandbox_git_commit) commits whatever is
staged. There's nothing to "apply."

9.3 Local mode (VS Code extension)

local_mode in ChatContext switches several tools to talk to a local
tunnel instead of the worktree. The plan: keep the local-mode path in
the agent layer, not the sandbox layer. When local_mode is on,
the agent uses a different tool set (the existing tunnel-backed tools)
and bypasses SandboxClient entirely. The sandbox library doesn't need
to know about VS Code.

9.4 Auth token handling

WorkspaceRequest.auth_token is already plumbed (the daytona adapter
embeds it via the #__potpie_token__=... marker; the local adapter
embeds it as x-access-token:...@host). Tokens are never persisted
(adapters/outbound/file/json_store.py:125). Keep that property — the
SandboxClient API takes the token at workspace creation, and the rest
of the system never sees it again. The implementer should keep the
auth-chain code (sync_helper.py) intact when it moves into the
adapter, since GitHub App → OAuth → env-token is more than the sandbox
should re-derive.

---

10. .repos as an adapter

After §9.6 the local-fs adapter lives at
adapters/outbound/local/. Concretely:

- repo_cache.py: bare-repo lifecycle (clone, fetch, GC, eviction).
Absorbs the meaningful parts of repo_manager.py.
- git_workspace.py (existing, expanded): worktree lifecycle on top of
the cache.
- subprocess_runtime.py (existing): host execution.
- auth.py: GitHub App → OAuth → env-token chain. Absorbs
sync_helper.py's logic.

Public behavior the local adapter must preserve:

- .repos/<owner>/<repo>/.bare/, .../worktrees/<name>/ paths — for
developer ergonomics and for the existing parsing flow which knows
these paths.
- REPOS_BASE_PATH env var — keep it as the config knob.
- GH_TOKEN, GH_TOKEN_LIST, GITHUB_BASE_URL env vars — keep them.
- The existing eviction policy — port it; don't re-design as part of this.

Things the local adapter may stop doing (because the sandbox layer
above it now does them):

- The .meta/<owner>/<repo>/branch__commit.json files. The
SandboxStore is now the source of truth for branch/commit/age
metadata. Migrate the data into the store on first read; delete the
files on write.

---

11. Prompt updates

System prompts in app/modules/intelligence/agents/chat_agents/system_
agents/code_gen_agent.py and the generic pydantic_agent.py reference
the old tool names extensively (lines 30–122 and 413–650+ in
code_gen_agent.py; lines 172–216 in pydantic_agent.py).

Update plan:

- Replace tool-name references with the new ones.
- Replace any "use CodeChangesManager to stage edits" framing with
"edit the file directly; the worktree is yours." Make explicit that
edits are durable from the moment the tool returns and that
sandbox_git_commit formalizes them.
- Add a short "Sandbox tools" section enumerating the catalog, mirroring
how bash_command_tool's description is structured.
- Verify the local_mode branch of the prompt still hangs together
given §9.3 — the local-mode tools stay, just without the sandbox
ones.

The prompts are long. The implementer should diff carefully and run the
agent against a small smoke test (the existing E2E in
agents/integration/) before declaring victory.

---

12. Phasing

Rough order; each phase is independently shippable.

1. Image + ripgrep. Ship potpie/agent-sandbox Docker image,
register as the daytona snapshot default. Verify rg, git, jq
present in all backends.
2. Client surface. SandboxClient over existing service. Helpers
(read_file, write_file, list_dir, search, commit, push).
Unit tests. No callers yet.
3. One sandbox per (user, project) for the daytona backend.
Worktree-per-branch inside it. New e2e test that two workspace
requests with different branches share the same Daytona sandbox.
4. Sandbox-backed agent tools registered in ToolService. Old
tools still present.
5. Migrate code_gen_agent to the new tools. Update its prompt.
Smoke test.
6. Migrate parsing. ParseHelper uses SandboxClient via local-fs
backend. Re-run parsing tests.
7. Migrate remaining agents. One per PR; same pattern as code_gen.
8. Delete CodeChangesManager. Including its Redis schema,
lifecycle plumbing, and the staging tool family.
9. Move .repos glue into the local adapter. Delete
app/modules/repo_manager/. Migrate .meta JSON state on first
read.
10. Durable store + Redis locks. When we go multi-worker.
11. Background eviction. Separate from the request path.

Phases 1–3 are foundational and can land concurrently. 4–7 are the
visible migration. 8–9 are the cleanup. 10–11 are scaling work, not
correctness work.

---

13. Open questions

These are real choices the implementer should make explicitly, not pretend
the plan answered:

- One image or two. Slim vs full. Cold start vs feature coverage.
Daytona snapshot pull time matters here — measure it.
- Per-user vs shared RepoCache. Sharing saves disk and clone time;
separating is simpler for auth and quota. Default to per-user; design
the key so we can flip later.
- Where the SandboxRunContext contextvar lives. Closest analogue
is _code_changes_manager_ctx in
code_changes_manager/context.py. Same pattern, different module.
- Whether to keep WorkspaceMode. ANALYSIS / EDIT / TASK currently
drive branch naming. Once parsing goes through us with mode=ANALYSIS
and agents with mode=EDIT, we have one more user (TASK?) — or we
collapse to two (read vs write). Simpler is better; collapse if the
test suite still passes.
- Streaming exec. exec_stream exists in the port but isn't used.
Promote it once an agent flow needs progress (long test runs, builds).
- PR creation. code_provider_create_pr is a tool today and lives
outside the sandbox. Either fold it into sandbox_open_pr (clean,
but ties auth to the sandbox lib), or keep it separate (clean
layering, slightly worse ergonomics). Lean toward separate.
- Multi-tenancy at the Daytona level. One Daytona org per potpie
deployment? Per user? The dev stack has one [email protected] user;
production needs a story. Out of scope here, but the sandbox client's
config shape should not preclude per-user Daytona credentials.

---

14. What this replaces, in one table

| Concept | Today | After |
| ---------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| Bare repo + worktree on disk | app/modules/repo_manager/ | app/src/sandbox/.../adapters/outbound/local/ |
| In-flight file edits | CodeChangesManager (Redis, 24h TTL) | The worktree + git |
| Edit-staging tools (~20) | code_changes_manager/tools.py | A dozen sandbox_* tools, mostly just file/git ops |
| Repo materialization for parsing | ParseHelper.clone_or_copy_repository → RepoManager | SandboxClient.get_workspace(mode=ANALYSIS) |
| Repo materialization for agents | Tool internals call get_or_create_edits_worktree_path per call | One SandboxClient.get_workspace per run, cached on ctx |
| Branch concurrency | One worktree per (user, repo, conversation) on disk | Many worktrees per Daytona sandbox; one cache per repo |
| Clone auth | sync_helper.py (GitHub App → OAuth → env) | Same code, lives in the local adapter |
| .repos directory | The blessed location | One adapter's storage; equivalent in Daytona is a sandbox |
| Eviction | Inline during prepare_for_parsing | Background task per adapter |
| Locks | None at app layer; OS file locks for git | LockManager per workspace; pluggable Redis impl |
| Durable store | DB tables for Project; JSON in .meta/ | SandboxStore (Postgres adapter when multi-worker) |
| Tool wiring | Hardcoded allow-lists + emerging registry | Registry-only; sandbox tools as a group |

---

If something in here looks underspecified, that's by design — the plan
should make the call points obvious without freezing the implementation.
The right next step is phase 1: build the image, snapshot it, and prove
rg is available in a Daytona sandbox end-to-end. Everything else
follows.

---

Vscode Extension Debug Handoff

VS Code Extension Debug/DAP Handoff

Date: 2026-05-25

Context

The debug agent can reach the local workspace over the Socket.IO tunnel, but C/C++
debugging currently fails or degrades in two ways:

1. Terminal commands such as gcc -g ... and mkdir ... can complete locally while
the backend waits until the RPC timeout because no tool_response is observed.
2. get_workspace_debug_context reports debug_adapters: ["python", "node"] even
on a macOS machine where LLDB and lldb-dap are installed. This blocks C/C++
debug session setup from the agent's point of view.

This is not expected to be a local network or WebSocket reliability problem. The
backend timeout means: tool_call was emitted, but no matching tool_response
arrived on Redis pub/sub before the timeout.

Latest isolated harness verification after the extension-side terminal fix:

- /api/terminal/execute for cc -g -o add_numbers add_numbers.c returned in
roughly 400ms with success=true, exit_code=0, empty stdout/stderr, and
timed_out=false.
- /api/workspace/debug-context returned C/C++-relevant adapters:
["python", "node", "lldb", "lldb-dap"].
- /api/debug/start-session with lldb-dap succeeded and returned a session id.
- /api/debug/set-breakpoints at add_numbers.c:4 returned a verified
breakpoint.
- /api/debug/snapshot after continue still failed with
Cannot take snapshot: session is running, expected paused.

That harness run was a smoke test, not a full DAP tool matrix. It did not cover
step-over, step-into, step-out, evaluate, list-sessions, or a clean
stop-session path.

Backend Contract

Socket event from backend to extension:

json
{
  "correlation_id": "<uuid>",
  "endpoint": "/api/terminal/execute",
  "payload": {},
  "timeout": 35.0
}

The extension must always respond with:

json
{
  "correlation_id": "<same uuid>",
  "success": true,
  "result": {}
}

or:

json
{
  "correlation_id": "<same uuid>",
  "success": false,
  "error": "..."
}

Important backend routes used by the debug agent:

| Endpoint | Purpose |
| --- | --- |
| /api/workspace/debug-context | Return launch configs, available debug adapters, inferred commands |
| /api/terminal/execute | Run shell commands in sync or async mode |
| /api/terminal/sessions/{session_id}/output | Poll async terminal output |
| /api/terminal/sessions/{session_id}/signal | Stop async terminal process |
| /api/debug/start-session | Start DAP debug session |
| /api/debug/set-breakpoints | Set breakpoints |
| /api/debug/snapshot | Capture stack/locals/expressions |
| /api/debug/list-sessions | List debug sessions |
| /api/debug/stop-session | Stop debug session |

Required Extension Changes

1. Always Emit tool_response

Every extension route handler must emit a response for every received
correlation_id, including:

- success with empty stdout
- non-zero exit
- thrown exception
- timeout
- unknown route
- debug adapter launch failure

This should be implemented with a top-level try/catch/finally around dispatch so
no handler can accidentally leave the backend waiting.

2. Fix Terminal Completion For Silent Commands

The terminal executor must not infer completion from visible terminal output.
Commands like these are valid and often produce no stdout:

bash
gcc -g -o add_numbers add_numbers.c
mkdir -p .vscode
true

The user-facing contract is that terminal commands should be visible in a VS Code
integrated terminal by default. A hidden child_process result is acceptable only
for an explicitly hidden/internal mode; it is not acceptable for normal debug-agent
terminal commands because users must be able to see what the agent ran.

Recommended behavior:

- Open or reuse a named integrated terminal such as Potpie.
- Show the command in that terminal before execution.
- Capture stdout, stderr, exit code, duration, and timeout for the RPC response.
- Append an internal sentinel to detect completion reliably when the command is
silent.
- Keep the terminal visible unless the payload explicitly requests hidden
execution.

Implementation options:

- If using an integrated terminal/PTY, append an explicit sentinel that includes
exit code, then parse that sentinel, e.g. printf "\n__POTPIE_EXIT:$?__\n".
- If using child_process.spawn / execFile, wire it only to an explicit hidden
mode or mirror the command/output into the visible terminal.

Expected sync result shape:

json
{
  "success": true,
  "command": "gcc -g -o add_numbers add_numbers.c",
  "output": "",
  "error": "",
  "exit_code": 0,
  "duration_ms": 1234
}

3. Return Accurate debug_adapters

debug_adapters should represent debug adapter types that the extension can
actually launch in the current VS Code/Cursor session.

For C/C++ on macOS, include at least one of:

- lldb when CodeLLDB (vadimcn.vscode-lldb) is available
- cppdbg when Microsoft C/C++ (ms-vscode.cpptools) is available
- lldb-dap or another explicit adapter id only if the extension start-session
handler can launch it directly

Do not infer this only from binaries on disk. /usr/bin/lldb and
/Library/Developer/CommandLineTools/usr/bin/lldb-dap prove the machine has LLDB,
but they do not prove VS Code has a registered adapter type unless the extension can
use them.

If the extension can launch /Library/Developer/CommandLineTools/usr/bin/lldb-dap
directly without a marketplace extension, return a capability that makes that
explicit, for example:

json
{
  "debug_adapters": ["python", "node", "lldb-dap"],
  "native_debuggers": {
    "lldb": "/usr/bin/lldb",
    "lldb_dap": "/Library/Developer/CommandLineTools/usr/bin/lldb-dap"
  }
}

4. Support C/C++ Launch Configs

The extension should accept launch configs from .vscode/launch.json and start
sessions for C/C++ configs such as:

json
{
  "type": "cppdbg",
  "request": "launch",
  "name": "Debug add_numbers",
  "program": "/Users/deepesh/work/valkey/add_numbers",
  "cwd": "/Users/deepesh/work/valkey",
  "MIMode": "lldb"
}

and/or CodeLLDB style:

json
{
  "type": "lldb",
  "request": "launch",
  "name": "Debug add_numbers",
  "program": "/Users/deepesh/work/valkey/add_numbers",
  "cwd": "/Users/deepesh/work/valkey"
}

If an adapter is missing, return a structured failure response instead of timing
out:

json
{
  "success": false,
  "error": "debug_adapter_unavailable",
  "message": "No registered debug adapter for type 'cppdbg'. Install ms-vscode.cpptools or use lldb."
}

5. Add Correlation-ID Tracing

Log these lifecycle points with correlation_id, endpoint, and workspace_id:

- received tool_call
- selected handler
- handler started
- handler completed
- emitted tool_response
- handler exception
- handler timeout

This is the fastest way to distinguish:

- backend emitted to stale socket id
- extension received but handler did not respond
- extension responded but socket server did not publish to Redis
- backend worker did not receive Redis pub/sub message

Acceptance Checks

With the extension connected to the workspace:

1. execute_terminal_command("true") returns exit code 0 without timeout.
2. execute_terminal_command("mkdir -p .vscode") returns exit code 0 without timeout.
3. execute_terminal_command("gcc -g -o add_numbers add_numbers.c") returns exit
code 0 without timeout, even with empty stdout.
4. get_workspace_debug_context includes the C/C++ adapter that the extension can
actually launch (lldb, cppdbg, or lldb-dap).
5. start_debug_session for the compiled add_numbers binary returns a session id
or a structured adapter-unavailable error; it must not time out silently.
6. set_breakpoints at add_numbers.c:4 and take_debug_snapshot return locals
when the program pauses.
7. User-facing terminal commands visibly open or reuse an integrated terminal and
show the command being run; the RPC response must not be produced only by a
hidden process in normal mode.

Backend Follow-Up Needed

The backend currently models start_debug_session.language as:

python
Literal["python", "node", "go", "unknown"]

To make C/C++ first-class, backend should add c, cpp`, or a direct launch-config
type field and pass through adapter-specific launch configs without forcing them
through language-only routing.

---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#agents Browse agents catalog → #ai-agents Browse ai-agents catalog → #ai-agents-framework Browse ai-agents-framework catalog → #artificial-intelligence Browse artificial-intelligence catalog → #context-graph Browse context-graph catalog → #developer-tools Browse developer-tools catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →