Add Ascii Box provider

[pkyanam]

Summary

• add an ascii() provider backed by the official @asciidev/box-sdk
• normalize binary/text files, directories, foreground commands, detached processes, cancellation, protected/public ports, persistent managed sessions, and snapshot capture
• preserve Box-specific capabilities through a typed AsciiBox raw handle
• add provider metadata, package exports, examples, documentation, capability declarations, and integration coverage

Why

Ascii Box offers persistent cloud computers and agent workflows, but applications currently need provider-specific code for its lifecycle, command, file, preview, and snapshot APIs. This adapter makes Box available through the same Sandbox SDK surface as the existing providers while retaining native SDK access for Box-specific features.

Implementation notes

• normalized /workspace paths map to Box's work-directory-relative API
• detached processes persist stdout, stderr, and exit state inside the Box and support signals
• protected preview credentials stay out of serialized URLs; request() handles Box's same-origin cookie bootstrap on server runtimes
• cleanup honors Box's recent-snapshot safeguard by archiving, waiting for a completed snapshot, and retrying deletion when required
• foreground commands retain Box's 60-second API limit; longer work uses the detached process surface

Validation

• bun run lint
• bun run typecheck
• bun run test — 45 passed, 18 credential-gated tests skipped, 0 failed
• BOX_API_KEY=... bun test tests/live/ascii.test.ts --timeout=360000 — 1 passed against a real Box, with one Box active at a time and zero active Boxes after cleanup
• bun install --frozen-lockfile
• npm pack --dry-run

[vercel]

@pkyanam is attempting to deploy a commit to the OpenCore Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

This PR adds an Ascii Box provider to the Sandbox SDK. The main changes are:

• New ascii() provider backed by @asciidev/box-sdk.
• Normalized files, commands, detached processes, protected ports, snapshots, and lifecycle handling.
• Typed AsciiBox raw handle for native Box API access.
• Package export, metadata, example, docs, and compatibility updates.
• Unit, type, package export, integration, and live test coverage for Ascii.

Confidence Score: 4/5

This PR is close, but the snapshot lifecycle bug should be fixed before merging.

A single contained issue affects Ascii snapshot creation and cleanup retry timing. The provider exports, metadata, docs, and test coverage otherwise line up with the new integration.

packages/sdk/src/providers/ascii/index.ts

T-Rex Logs

What T-Rex did

• The focused Bun test harness reproduced the scenario by importing the real Ascii provider via createSandbox and mocking the Box SDK snapshot API sequence.
• The test run showed the mocked trace where getLatestBoxSnapshot returned snap-0 completed, snap-1 pending, and snapshots.create returned snap-1 immediately, with no third poll before the SDK result was returned.
• SDK validation steps completed: frozen install, lint, typecheck, and ASCII unit-and-exports checks all completed successfully.
• Packaging and credential gating checks completed: npm pack dry-run listed Ascii provider artifacts in the tarball, and live Ascii tests were skipped because BOX_API_KEY_PRESENT was redacted.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
packages/sdk/src/providers/ascii/index.ts	Adds the Ascii provider implementation; snapshot polling should wait for completed snapshots before returning or retrying cleanup.
packages/sdk/src/providers/capabilities.ts	Declares Ascii capability support consistent with the normalized provider surface.
packages/sdk/src/metadata.ts	Adds Ascii provider metadata, package details, credential variables, and behavior notes.
packages/sdk/package.json	Publishes the ./ascii export and optional peer dependency for @asciidev/box-sdk.
packages/sdk/tests/providers/ascii.test.ts	Adds mocked unit coverage for Ascii files, commands, ports, detached processes, snapshots, sessions, and error mapping.
packages/sdk/tests/live/ascii.test.ts	Adds credential-gated live smoke coverage for the new Ascii provider.
apps/fumadocs/content/docs/providers/ascii.mdx	Adds the Ascii provider documentation page with auth, lifecycle, ports, snapshots, and native API notes.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant App
participant SDK as Sandbox SDK
participant API as Ascii API
participant Runtime as Box Runtime

App->>SDK: Create sandbox with ascii provider
SDK->>API: Create Box
SDK->>API: Poll Box state until ready
App->>SDK: Use files commands processes or ports
SDK->>API: Call file and command endpoints
API->>Runtime: Execute operation in work directory
App->>SDK: Create snapshot
SDK->>API: Archive Box
SDK->>API: Wait for latest snapshot
SDK->>API: Resume Box
App->>SDK: Stop sandbox
SDK->>API: Remove Box
alt Recent snapshot required
  SDK->>API: Archive Box and wait for snapshot
  SDK->>API: Retry remove
end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant App
participant SDK as Sandbox SDK
participant API as Ascii API
participant Runtime as Box Runtime

App->>SDK: Create sandbox with ascii provider
SDK->>API: Create Box
SDK->>API: Poll Box state until ready
App->>SDK: Use files commands processes or ports
SDK->>API: Call file and command endpoints
API->>Runtime: Execute operation in work directory
App->>SDK: Create snapshot
SDK->>API: Archive Box
SDK->>API: Wait for latest snapshot
SDK->>API: Resume Box
App->>SDK: Stop sandbox
SDK->>API: Remove Box
alt Recent snapshot required
  SDK->>API: Archive Box and wait for snapshot
  SDK->>API: Retry remove
end

Loading

_{Reviews (1): Last reviewed commit: "Add Ascii Box provider" | Re-trigger Greptile}

[greptile-apps]

Wait for completion
waitForSnapshot() returns the first snapshot whose id differs from previousId without checking that Box has finished it. When archive() exposes a new snapshot while it is still pending, sandbox.snapshots.create() returns a not-yet-restorable artifact and removeBox() immediately retries deletion against the same incomplete safety snapshot, so cleanup can still fail despite the intended safeguard. I’m 4/5 confident this should check the snapshot status before returning.

Artifacts

Repro: focused Bun test harness mocking pending then completed Ascii snapshots

• Contains supporting evidence from the run (text/typescript; charset=utf-8).

Repro: Bun test output showing pending snapshot returned before completion poll

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}