feat(sandbox): add Ascii Box workspace provider

[usehoplite]

Summary

Akeru could not create or reconnect to Ascii Box workspaces. Add an ascii sandbox adapter using the official @asciidev/box-sdk (pinned to 0.0.37), following the existing remote-workspace identity and credential patterns.

• Create credential-isolated persistent Linux VMs, reattach by saved VM ID, inspect lifecycle state, wait for native snapshot archival before resuming, and delete with explicit SDK confirmation. Transient lifecycle and setup failures preserve remote VMs and identities for retry.
• Execute quoted commands with working-directory and environment handling; reject unsupported command timeouts above the Box API’s ten-minute limit before execution; route protected, token-authenticated browser endpoints without forwarding API credentials.
• Coordinate shared Railway VM creation and deletion across credential-scoped clients, preserving active leases during credential rotation.
• Register the provider in contracts, settings, secret redaction, bot selectors and analytics. Add lifecycle/credential tests, user documentation and a minor changeset.
• Capture credential input values before React clears the event; the existing handler crashed when entering the new provider's key.

Capability reference: https://sandbox-sdk.app/docs/providers. The official SDK README says Box is now Boat: this requested integration uses the frozen Box API, supported until its provider-announced sunset.

Verification

• Shared Railway identity lifecycle: 134 focused workspace/pool/session-resource/Tenki tests passed; server typecheck passed. Credential-rotated clients serialize VM creation and defer/deduplicate shared deletion. Targeted lint: zero errors, one unchanged no-this-alias warning.

• Current adapter/pool/session-resource pass: 106 tests passed, including setup-failure recovery, bounded readiness polling, and command-timeout validation. Server typecheck and targeted lint passed.

• Late-deletion recovery: 53 workspace/pool tests passed. A confirmed Ascii lookup 404 replaces the missing VM and saves its new identity; auth/server/transport errors preserve the original. Failed replacement creation remains retryable. Server typecheck and targeted lint passed.

• Confirmed deletion follow-up: 49 adapter/pool tests passed, including asynchronous deletion completion, bounded timeout, and identity retention on blocked deletion followed by retry. Server typecheck and targeted lint passed. VM identities are removed only after deletion completes.

• Analytics upgrade compatibility: 17 focused contract/service tests passed. Persisted pre-Ascii retry queues drain with zero-filled Ascii counters and stable insert IDs; invalid explicit values remain rejected. Contracts and server typechecks and targeted lint passed.

• 163 tests passed across 7 focused files: workspace adapters, server settings, contract settings/bot config/analytics, sandbox settings logic, and bot sandbox selection.

• Server, web and contracts typechecks passed. Changed-file formatting and git diff --check passed. Targeted lint: no errors; one pre-existing unused-variable warning in settings.test.ts.

• Isolated Chromium check against an explicit worktree-local home: enter a fixture key, connect Ascii Box, select it as default, reload and verify persistence, verify key redaction, disconnect and verify Local fallback after reload. Fixture connection removed afterward.

• Live Ascii Box provisioning/commands/previews were not exercised: no Box API credential was available. SDK-boundary mocks cover lifecycle and execution. Follow-up verification: 49 adapter, pool and browser tests passed, including transient-failure preservation, protected browser URLs, command timeout limits, and asynchronous snapshot completion/error/timeout cases. Server typecheck and targeted lint passed. Web verifies the shared desktop renderer; no Electron shell or React Native code changed. Existing provider-driver paths continue to use the shared workspace factory.

Screenshots

Before: Settings → Sandbox on main lists Tenki as the last provider.

After: Ascii Box and Railway (from #303, which this branch builds on) appear in the provider list.

Ascii Box connects with a single API key.

Implemented with OpenAI GPT-6 Astra in the Hoplite harness.

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
akeru-bot-landing	Building	Preview	Sep 28, 2026 3:30pm UTC

[devin-ai-integration]

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 6 potential issues.

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds a new sandbox provider for persistent Linux VMs.

The PR appears safe to merge, with no new blocking finding; an existing non-blocking setup-error delay remains.

Summary

The PR adds Ascii Box as a persistent remote sandbox, with credential handling, VM lifecycle operations, protected browser access, settings, analytics, tests, and documentation. The latest change adjusts how Railway deletion reports an earlier idle-client failure after shared deletion succeeds.

_{Reviews (10) · Last reviewed commit: "fix(sandbox): accept successful shared R..."}

[usehoplite]

Addressed the code findings in 1211062, b379126 and e38c6ac:

• Transient wake/stop failure deletes a VM (Devin #4124126536; Greptile #4124178465): the pool now evicts failed remote handles without invoking destructive cleanup. A subsequent acquire can reattach using the preserved identity; explicit teardown still deletes. Local-resource cleanup remains unchanged. Regression tests cover initial wake failure, wake after idle, idle-stop failure and explicit deletion.
• Public browser-control endpoint (Devin #4124127461; Greptile #4124178450): request public: false, require a protected response with its _token query credential, and reject unprotected endpoints. The API key is never forwarded. The existing browser transport preserves the entire endpoint URL.
• Inherited account secrets (#4124127698): new VMs set noEnv: true. Resume preserves the existing VM configuration rather than unexpectedly changing it.
• Command timeout default (#4124126801): unspecified timeouts explicitly use the provider maximum of 600 seconds rather than an undocumented provider default; supplied timeouts are converted and bounded to the documented 1–600-second range.
• Snapshot completion (#4124127277): the SDK's stop API starts archival asynchronously. Sleep now waits for archived, and wake waits through archiving before resuming. Bounded waits surface error/timeout without deleting data. Tests use fake timers, not real-time sleeps.

Validation: 48 focused adapter/pool/browser tests passed; server typecheck, changed-file formatting and targeted lint passed. No live Ascii credentials are available, so hosted behavior remains SDK-mock verified.

UI evidence request (#4124127068) remains limited: the initial implementation captured and inspected a current screenshot and exercised connect/default/reload/redaction/disconnect in isolated Chromium. This harness has no authorized GitHub attachment-upload path, and I have not committed PR-only assets or represented the current screenshot as a pre-change baseline. The PR explicitly records this evidence limitation.

[usehoplite]

Fixed the queued analytics upgrade regression in 43f138d. sandbox_turns_ascii now defaults to zero only when omitted, matching the existing new_installations compatibility pattern. Explicit invalid values remain rejected, and valid counts are preserved.

The server integration test now rewrites a persisted retry queue into the pre-Ascii shape, reloads and delivers it, and verifies zero-filled Ascii counters and stable insert IDs. Both queued buckets drain successfully.

Verification: 17 contract/analytics service tests passed; contracts and server typechecks passed; targeted lint, formatting, and diff checks passed. No UI behavior changed in this follow-up.

[usehoplite]

Addressed the asynchronous deletion finding in a61102973: Ascii destroy() now polls the SDK deletion operation until completed. Blocked operations and bounded timeouts reject, so the wrapper retains provider.json. Tests cover pending completion, timeout, and blocked deletion retaining the identity followed by a successful retry. All 49 focused adapter/pool tests, server typecheck, formatting and targeted lint passed.

The automatic replacement suggestion for failed remote wake is intentionally not applied. A wake failure is not proof that the workspace is irrecoverably gone: permission failures, network errors, stalled snapshots and provider error states can all leave recoverable data. The existing saved-identity contract deliberately fails closed and explicitly tells the operator how to remove the identity to request a replacement (createRemoteBotWorkspace, covered by the missing/unavailable reattachment test). Silent replacement would abandon durable work and contradict this PR's earlier data-loss fix. Pool eviction permits retries against the same saved VM; explicit destruction remains supported. A user-confirmed replacement flow would be a separate product change, not a safe consequence of a generic wake rejection.

[usehoplite]

Addressed the new adapter review in 617d396:

• Setup cleanup: confirmed. Ascii now follows the persistent Railway/Tenki cleanup path, retaining the workspace instead of destroying it when initialization fails. A regression test covers failure, non-destructive release, and successful reacquisition.
• Readiness deadline: the pinned @asciidev/box-sdk 0.0.37 already bounds waitUntilReady via its poll helper (default timeoutMs 300000). The claimed indefinite successful-status polling is not present. The adapter now passes that deadline explicitly, with a regression test for a persistently provisioning VM.
• Command duration: confirmed silent truncation. Box only accepts 1–600 seconds, per its generated CommandRequest contract. Unsupported timeouts now fail clearly before execution rather than running with a shortened limit. User docs describe this constraint.

Verification: 106 focused adapter/pool/session-resource tests passed; server typecheck and targeted lint passed. Live Box verification remains unavailable without credentials. The existing minor changeset covers these fixes to the new provider.

[usehoplite]

Addressed the two Railway P1 findings in d3bf2e7. Credential-scoped clients now coordinate acquisition/release by durable VM identity. Creation is serialized, explicit deletion waits for the final identity lease, idle clients are invalidated, and deletion is deduplicated across credential keys and shutdown. Regression tests cover concurrent creation, shared leases, pending acquisition vs deletion, stale idle clients, fresh VM generations, and cleanup failure.

The Ascii P2 timing observation is accurate, but I am retaining awaited cleanup deliberately: reporting acquisition as finished while snapshot archival remains active would allow retry/shutdown to race an unfinished resource release. This is bounded archival polling, not an indefinitely stuck acquisition, and preserves the existing data-safety contract. docs/user/sandboxes.md now states that setup errors and retries can wait for snapshot cleanup (up to five minutes of archival polling). No detached cleanup worker was introduced.

Verification: 134 focused workspace/pool/session-resource/Tenki tests passed; server typecheck passed; targeted lint had zero errors and one unchanged no-this-alias warning. Existing provider-feature changesets cover these fixes. No live cloud resources were used.

[usehoplite]

Fixed the new successful-deletion-reports-failure finding in this push. An idle Railway credential client failure is now distinguished from other cleanup failures: when another credential client completes the shared deletion, release succeeds. If deletion never succeeds, the original deletion error still propagates; unrelated cleanup errors remain errors. Added the revoked-old-token/current-token regression and retained the all-clients-fail regression. 72 focused pool/session-resource tests passed; server typecheck passed; targeted lint has no errors and one unchanged warning. Existing feature changesets cover this correction. The separate Ascii snapshot-cleanup timing rationale remains unchanged and documented.