1  # SDKs AGENTS
  2  
  3  You are working on OpenSandbox SDKs. Keep generated and handwritten code separate, and keep behavior aligned across languages when the same capability exists in multiple SDKs.
  4  
  5  ## Scope
  6  
  7  - `sandbox/**`
  8  - `code-interpreter/**`
  9  - `mcp/**`
 10  
 11  If the task is driven by spec changes, also read `../specs/AGENTS.md`.
 12  
 13  ## Key Areas
 14  
 15  - `sandbox/python`, `sandbox/javascript`, `sandbox/kotlin`, `sandbox/csharp`
 16  - `code-interpreter/python`, `code-interpreter/javascript`, `code-interpreter/kotlin`, `code-interpreter/csharp`
 17  - `mcp/`
 18  - Workspace config in `package.json`, `pnpm-workspace.yaml`, and shared build files
 19  
 20  ## Generated Code
 21  
 22  Do not manually edit generated code as the only fix.
 23  
 24  Generator-owned paths include:
 25  
 26  - `sandbox/python/src/opensandbox/api/**`
 27  - `sandbox/javascript/src/api/*.ts`
 28  - `sandbox/kotlin/sandbox-api/build/generated/**`
 29  
 30  Handwritten logic belongs in adapters, services, facades, converters, and stable SDK models.
 31  
 32  ## Commands
 33  
 34  Workspace JS install:
 35  
 36  ```bash
 37  cd sdks
 38  pnpm install --frozen-lockfile
 39  ```
 40  
 41  JavaScript SDK checks:
 42  
 43  ```bash
 44  cd sdks
 45  pnpm run lint:js
 46  pnpm run typecheck:js
 47  pnpm run build:js
 48  pnpm run test:js
 49  ```
 50  
 51  Python sandbox SDK:
 52  
 53  ```bash
 54  cd sdks/sandbox/python
 55  uv sync
 56  uv run python scripts/generate_api.py
 57  uv run ruff check
 58  uv run pyright
 59  uv run pytest tests/ -v
 60  uv build
 61  ```
 62  
 63  JavaScript sandbox SDK:
 64  
 65  ```bash
 66  cd sdks/sandbox/javascript
 67  pnpm run gen:api
 68  pnpm run lint
 69  pnpm run typecheck
 70  pnpm run build
 71  pnpm run test
 72  ```
 73  
 74  Kotlin sandbox SDK:
 75  
 76  ```bash
 77  cd sdks/sandbox/kotlin
 78  ./gradlew :sandbox-api:generateLifecycleApi :sandbox-api:generateExecdApi :sandbox-api:generateEgressApi
 79  ./gradlew spotlessApply :sandbox:test
 80  ```
 81  
 82  ## Guardrails
 83  
 84  Always:
 85  
 86  - For spec-driven changes, regenerate affected SDK code, update handwritten layers, then run affected language checks.
 87  - Add a regression test for every bug fix.
 88  - Prefer tests for request mapping, response conversion, error mapping, streaming behavior, and resource cleanup.
 89  - Keep package-local validation fast before widening to multi-language verification.
 90  - Match public behavior across languages unless a documented platform constraint prevents it.
 91  - Keep wire-format units and public SDK units separate. Public SDK interfaces should expose time durations as language-native duration types where available (`timedelta`, `Duration`) or otherwise as explicitly second-based fields such as `timeoutSeconds`.
 92  
 93  Ask first:
 94  
 95  - Public breaking changes
 96  - Large cross-language refactors
 97  - Intentional behavior drift between languages
 98  
 99  Never:
100  
101  - Patch generated output as the only fix.
102  - Change SDK public behavior without tests.
103  - Mix unrelated non-SDK work into an SDK change.
104  
105  ## Good Patterns
106  
107  - Generated clients for normal request/response APIs
108  - Handwritten transport only for streaming or protocol-specific paths such as SSE