docs: retract planned `sandbox-compute-adapter.mdx` — upstream `SandboxToComputeAdapter` removed as dead code (PraisonAI#2913)

[MervinPraison]

Source change

Tracking documentation impact of upstream commit MervinPraison/PraisonAI@4cc68e6 on branch claude/confident-fermat-u1carn:

fix: remove dead SandboxToComputeAdapter class (fixes #2913)

The SandboxToComputeAdapter class in sandbox/_compat.py had zero call sites across the entire src/ tree and was not exported anywhere. Its docstring falsely advertised deduplication between the sandbox/* and integrations/compute/* hierarchies that never occurred.

Removed the dead class and trimmed the module docstring to accurately describe the actively-used safe_sandbox_path() path-traversal guard, which remains unchanged and is still imported by docker.py/subprocess.py.

File touched: src/praisonai/praisonai/sandbox/_compat.py (+1/-181 lines)

---

Why this issue exists (context matters)

This change directly retracts one work-item from a previously-closed docs issue. See #306 (closed 2026-06-03 as "completed"), specifically §3 — CREATE docs/features/sandbox-compute-adapter.mdx, which asked for a new "Sandbox & Compute Unified Architecture" page built around SandboxToComputeAdapter.

That §3 was written on the premise that the legacy sandbox classes (DockerSandbox, DaytonaSandbox, ModalSandbox) had become thin wrappers around SandboxToComputeAdapter, unifying the sandbox/* and integrations/compute/* hierarchies.

That premise was never actually true in the code. The upstream commit message is explicit:

Its docstring falsely advertised deduplication between the sandbox/* and integrations/compute/* hierarchies that never occurred.

So issue #306 got closed but §3's docs/features/sandbox-compute-adapter.mdx page was never created (confirmed: no file, no git history for it, no docs.json entry). That was the right outcome by accident — this issue makes it explicit so nobody re-opens the work later.

---

Documentation impact assessment

1. docs/features/sandbox-compute-adapter.mdx — DO NOT CREATE

• Status: never existed in the repo (git log shows no add/delete for this path).
• Action: explicitly retract this work item from docs: cover PR #1615 — framework adapter signature, working PraisonAI adapter, unified Sandbox↔Compute, lazy import-time behavior #306. The class it would have documented no longer exists, and the "unified hierarchy" it would have described never actually existed either.
• If a future agent revisits docs: cover PR #1615 — framework adapter signature, working PraisonAI adapter, unified Sandbox↔Compute, lazy import-time behavior #306's acceptance checklist, they must skip the sandbox-compute-adapter.mdx bullet.

2. docs/security.mdx line 269 — still accurate, no change needed

Current text:

- Helper: `praisonai.sandbox._compat.safe_sandbox_path()`.

safe_sandbox_path() was preserved by the upstream commit — only the dead adapter class was removed. The reference remains correct.

Verification — the trimmed _compat.py (post-change) is now 30 lines total and exports exactly one public symbol, safe_sandbox_path, called by docker.py and subprocess.py:

"""Path-safety helper for sandbox backends."""

import logging
import os

logger = logging.getLogger(__name__)


def safe_sandbox_path(temp_dir: str | None, path: str) -> str | None:
    """Resolve a caller-supplied path to an absolute path inside temp_dir.

    Returns None if the resolved path would escape the sandbox root,
    preventing path-traversal attacks via sequences like `../../../etc/passwd`.
    ...
    """

No action required in docs/security.mdx.

3. praisonai/sandbox/_compat.py (synced code mirror in this repo)

The file at praisonai/sandbox/_compat.py in this repo is a synced code mirror maintained by update_repos.sh / .github/workflows/update-repos.yml, not documentation. The next daily sync will automatically replace it with the trimmed 30-line upstream version. No manual action required.

4. docs.json

No sidebar entry references sandbox-compute-adapter (verified: grep -r 'sandbox-compute-adapter' docs.json returns nothing). No docs.json change required.

5. Everything else

Full grep of docs/ for SandboxToComputeAdapter, ComputeAdapter, sandbox-compute-adapter returned zero hits. The removed class was never documented user-facing, so no page needs to be updated or deleted.

---

Summary — what the follow-up agent needs to do

Very little. This is not a "create/update pages" issue — it's a "confirm nothing is stale" issue with one retraction.

• Confirm docs/features/sandbox-compute-adapter.mdx does not exist and do not create it. This work item from docs: cover PR #1615 — framework adapter signature, working PraisonAI adapter, unified Sandbox↔Compute, lazy import-time behavior #306 is retracted.
• Confirm docs/security.mdx line ~269 still references praisonai.sandbox._compat.safe_sandbox_path() and leave it as-is (function still exists post-change).
• No docs.json edit needed.
• Do not manually edit praisonai/sandbox/_compat.py — the daily sync workflow will pick up the trimmed upstream version automatically.
• Close this issue with state_reason: completed once the two "confirm" boxes above are ticked.

If any of the confirmations fail (e.g. someone did create sandbox-compute-adapter.mdx between the closure of #306 and now), then:

• Delete docs/features/sandbox-compute-adapter.mdx (the class it documents is gone).
• Remove any docs.json entry pointing at it.
• Reply on this issue with the deletion PR link.

---

Reference — files in the source change

File	Change	Doc impact
src/praisonai/praisonai/sandbox/_compat.py	Removed SandboxToComputeAdapter class (185 lines); trimmed module docstring; kept safe_sandbox_path() unchanged	None (class was never user-facing)

Related

• Upstream commit: MervinPraison/PraisonAI@4cc68e6
• Upstream issue fixed: Dead adapter class in praisonai/sandbox/_compat.py (SandboxToComputeAdapter) never wired in PraisonAI#2913
• Previously closed docs issue this partially retracts: docs: cover PR #1615 — framework adapter signature, working PraisonAI adapter, unified Sandbox↔Compute, lazy import-time behavior #306 (§3)

---

Filed by docs-triage routine. This issue is intentionally a "nothing-to-do" record because the previously-closed #306 planned a page for a class that has now been deleted as never-really-used dead code. The retraction is the point.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Retraction verification — issue #1863

All confirmations pass. No documentation changes required — this is a "nothing-to-do" retraction record and the repo is already in the correct state.

• docs/features/sandbox-compute-adapter.mdx does NOT exist — confirmed (Glob returned no file). Correctly left uncreated; §3 of docs: cover PR #1615 — framework adapter signature, working PraisonAI adapter, unified Sandbox↔Compute, lazy import-time behavior #306 is retracted.
• docs/security.mdx:269 still references `praisonai.sandbox._compat.safe_sandbox_path()` — confirmed, left as-is (function preserved upstream).
• No docs.json entry references sandbox-compute-adapter — confirmed (grep: no match).
• No docs/ file references SandboxToComputeAdapter / ComputeAdapter — confirmed (grep: no match).

Outcome

The dead SandboxToComputeAdapter class was never user-facing and never documented, so nothing is stale. No file needs to be created, deleted, or edited; no docs.json change; no PR opened. The synced mirror praisonai/sandbox/_compat.py will be trimmed automatically by the daily update-repos workflow — left untouched as instructed.

This issue can be closed with state_reason: completed.

---

Branch: claude/issue-1863-20260711-1703 (no changes) · Job run

[praisonai-triage-agent]

🔄 Re-triggering Claude analysis (manual dispatch).

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Retraction verification — issue #1863

This is a "nothing-to-do" retraction record, not a create/update-page task. All required confirmations pass and the repo is already in the correct state.

• docs/features/sandbox-compute-adapter.mdx does NOT exist — confirmed (Glob returned no file). Correctly left uncreated; §3 of docs: cover PR #1615 — framework adapter signature, working PraisonAI adapter, unified Sandbox↔Compute, lazy import-time behavior #306 is retracted.
• docs/security.mdx:269 still references `praisonai.sandbox._compat.safe_sandbox_path()` — confirmed, left as-is (function preserved upstream).
• No docs.json entry references sandbox-compute-adapter — confirmed (grep: no match).
• No docs/ file references SandboxToComputeAdapter / ComputeAdapter / sandbox-compute-adapter — confirmed (grep: zero hits).

Outcome

The dead SandboxToComputeAdapter class was never user-facing and never documented, so nothing is stale. No file created, deleted, or edited; no docs.json change; no PR opened — creating a page for a now-deleted class would directly contradict this issue's intent. The synced mirror praisonai/sandbox/_compat.py will be trimmed automatically by the daily update-repos workflow — left untouched as instructed.

This issue can be closed with state_reason: completed.

---

Branch: claude/issue-1863-20260714-1502 (no changes) · Job run