claude-sandbox-sdk 0.1.0__tar.gz

claude_sandbox_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Validate tag matches pyproject version
+        env:
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          m = re.fullmatch(r"v(\d+\.\d+\.\d+)", tag)
+          if not m:
+            raise SystemExit(f"Unexpected tag format: {tag} (expected vX.Y.Z)")
+          tag_version = m.group(1)
+
+          text = Path("pyproject.toml").read_text(encoding="utf-8")
+          m2 = re.search(r"(?m)^version\s*=\s*\"([^\"]+)\"\s*$", text)
+          if not m2:
+            raise SystemExit("Could not find version = \"...\" in pyproject.toml")
+          project_version = m2.group(1)
+
+          if tag_version != project_version:
+            raise SystemExit(f"Tag version {tag_version} != pyproject.toml version {project_version}")
+
+          print(f"OK: {tag} matches pyproject.toml version {project_version}")
+          PY
+
+      - name: Build
+        run: python -m build
+
+      - name: Publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*

claude_sandbox_sdk-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log

claude_sandbox_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI302
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_sandbox_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: claude-sandbox-sdk
+Version: 0.1.0
+Summary: Claude Sandbox SDK — 管理 Claude Agent 沙盒服务的 CLI 工具
+Project-URL: Homepage, https://github.com/ai302/claude-sandbox-sdk
+Project-URL: Repository, https://github.com/ai302/claude-sandbox-sdk
+Project-URL: Issues, https://github.com/ai302/claude-sandbox-sdk/issues
+Author: AI302
+License: MIT
+License-File: LICENSE
+Keywords: agent,claude,sandbox,sdk,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: claude-agent-sdk>=0.2.91
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Claude Sandbox SDK
+
+管理 Claude Agent 沙盒服务的 CLI 工具。
+
+## 安装
+
+```bash
+pip install claude-sandbox-sdk
+```
+
+## 使用
+
+### 启动服务
+
+```bash
+# 前台运行
+claude-sandbox start
+
+# 后台运行
+claude-sandbox start --daemon
+
+# 指定端口
+claude-sandbox start --port 8300
+
+# 指定地址和端口
+claude-sandbox start --host 127.0.0.1 --port 8300
+```
+
+### 停止服务
+
+```bash
+claude-sandbox stop
+
+# 强制终止
+claude-sandbox stop --force
+```
+
+### 重启服务
+
+```bash
+claude-sandbox restart
+
+# 重启并更换端口
+claude-sandbox restart --port 8300
+```
+
+### 查看状态
+
+```bash
+claude-sandbox status
+```
+
+### 查看日志
+
+```bash
+# 查看最近 50 行
+claude-sandbox logs
+
+# 实时跟踪
+claude-sandbox logs --follow
+
+# 查看最近 100 行
+claude-sandbox logs --lines 100
+```
+
+## 配置
+
+配置优先级: CLI 参数 > 环境变量 > 默认值
+
+| 配置项 | 环境变量 | 默认值 |
+|-------|---------|-------|
+| host | `CLAUDE_SANDBOX_HOST` | 0.0.0.0 |
+| port | `CLAUDE_SANDBOX_PORT` | 8200 |
+| log_level | `CLAUDE_SANDBOX_LOG_LEVEL` | INFO |
+
+## 数据目录
+
+服务运行时数据存储在 `~/.claude-sandbox/`:
+
+- `pid` — 运行中的进程 PID
+- `port` — 当前使用的端口
+- `server.log` — 服务日志
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/ai302/claude-sandbox-sdk.git
+cd claude-sandbox-sdk
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 代码检查
+ruff check .
+mypy app/
+```
+
+## 发布
+
+```bash
+# 构建
+python -m build
+
+# 上传到 PyPI
+twine upload dist/*
+```
+
+## API 端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 健康检查 |
+| `/sessions` | GET | 列出会话 |
+| `/sessions/{id}` | GET | 获取会话信息 |
+| `/sessions/{id}/messages` | GET | 获取会话消息 |
+| `/ws/chat` | WebSocket | 聊天接口 |
+
+## License
+
+MIT

claude_sandbox_sdk-0.1.0/README.md

@@ -0,0 +1,124 @@
+# Claude Sandbox SDK
+
+管理 Claude Agent 沙盒服务的 CLI 工具。
+
+## 安装
+
+```bash
+pip install claude-sandbox-sdk
+```
+
+## 使用
+
+### 启动服务
+
+```bash
+# 前台运行
+claude-sandbox start
+
+# 后台运行
+claude-sandbox start --daemon
+
+# 指定端口
+claude-sandbox start --port 8300
+
+# 指定地址和端口
+claude-sandbox start --host 127.0.0.1 --port 8300
+```
+
+### 停止服务
+
+```bash
+claude-sandbox stop
+
+# 强制终止
+claude-sandbox stop --force
+```
+
+### 重启服务
+
+```bash
+claude-sandbox restart
+
+# 重启并更换端口
+claude-sandbox restart --port 8300
+```
+
+### 查看状态
+
+```bash
+claude-sandbox status
+```
+
+### 查看日志
+
+```bash
+# 查看最近 50 行
+claude-sandbox logs
+
+# 实时跟踪
+claude-sandbox logs --follow
+
+# 查看最近 100 行
+claude-sandbox logs --lines 100
+```
+
+## 配置
+
+配置优先级: CLI 参数 > 环境变量 > 默认值
+
+| 配置项 | 环境变量 | 默认值 |
+|-------|---------|-------|
+| host | `CLAUDE_SANDBOX_HOST` | 0.0.0.0 |
+| port | `CLAUDE_SANDBOX_PORT` | 8200 |
+| log_level | `CLAUDE_SANDBOX_LOG_LEVEL` | INFO |
+
+## 数据目录
+
+服务运行时数据存储在 `~/.claude-sandbox/`:
+
+- `pid` — 运行中的进程 PID
+- `port` — 当前使用的端口
+- `server.log` — 服务日志
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/ai302/claude-sandbox-sdk.git
+cd claude-sandbox-sdk
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 代码检查
+ruff check .
+mypy app/
+```
+
+## 发布
+
+```bash
+# 构建
+python -m build
+
+# 上传到 PyPI
+twine upload dist/*
+```
+
+## API 端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 健康检查 |
+| `/sessions` | GET | 列出会话 |
+| `/sessions/{id}` | GET | 获取会话信息 |
+| `/sessions/{id}/messages` | GET | 获取会话消息 |
+| `/ws/chat` | WebSocket | 聊天接口 |
+
+## License
+
+MIT

claude_sandbox_sdk-0.1.0/app/claude_sandbox_sdk/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Sandbox SDK — 管理 Claude Agent 沙盒服务的 CLI 工具"""
+
+__version__ = "0.1.0"

claude_sandbox_sdk-0.1.0/app/claude_sandbox_sdk/assets/media-studio-agent/.claude/agents/3d-executor.md

@@ -0,0 +1,143 @@
+---
+name: 3d-executor
+description: "3D model generation specialist. Executes ai302 3d create commands with --wait --short. Supports T23D and I23D. Use when the orchestrator needs 3D model generation."
+tools: Bash, Read, Glob
+model: inherit
+skills:
+  - 302ai-contracts
+---
+
+You are a 3D executor. You receive task descriptions from the orchestrator and execute `ai302 3d` commands. You return structured results with exact field names.
+
+## Your domain
+
+3D model generation only. Two CLI commands:
+- `ai302 3d create --wait --short` (blocking with internal polling) — generate 3D model
+- `ai302 3d fetch --short` (poll async results for pending tasks)
+- `ai302 3d models` (list supported models, read-only)
+
+## Kind inference
+
+- `--image` present → I23D (image-to-3D)
+- `--image` absent → T23D (text-to-3D, requires `--prompt`)
+
+## Workflow
+
+### Step 1 — Parse task_description
+
+Extract from the orchestrator's task_description:
+- `prompt`: text description — required for T23D
+- `image`: source image URL — present for I23D, repeatable
+- `model`: 3D model name — may be specified
+- `fileformat`: output format (`glb`, `usdz`, `fbx`, `obj`, `stl`) — optional
+- `material`: material type (`PBR`, `Shaded`, `All`, `None`) — optional
+- `quality`: quality level (`high`, `medium`, `low`, `extra-low`) — optional
+- `tier`: `Regular` or `Sketch` — optional
+- `mesh_mode`: `Raw` or `Quad` — optional
+- `subdivisionlevel`: `high`, `medium`, `low` — optional
+- `extra`: JSON object string — optional
+
+### Step 2 — Resolve model
+
+If `model` in task_description → use it.
+If not → discover:
+```bash
+ai302 3d models
+```
+Returns: `{"status":"completed","t23d":["model1",...],"i23d":["model2",...]}`
+Pick the first model from the matching kind list (t23d or i23d).
+
+### Step 3 — Read domain knowledge (if needed)
+
+```
+Read knowledge/3d.md
+```
+Only read when you need parameter details or backend-specific options.
+
+### Step 4 — Build and execute CLI command
+
+**T23D:**
+```bash
+ai302 3d create --prompt "<prompt>" --model "<model>" --wait --short [options]
+```
+
+**I23D:**
+```bash
+ai302 3d create --image "<url>" --model "<model>" --wait --short [options]
+```
+
+Optional flags (only when provided):
+- `--fileformat <format>`
+- `--material <type>`
+- `--quality <level>`
+- `--tier <tier>`
+- `--mesh_mode <mode>`
+- `--subdivisionlevel <level>`
+- `--extra '<json>'`
+
+### Step 5 — Parse response and return
+
+**Completed (`--wait` succeeded):**
+```json
+{"status": "completed", "taskid": "<id>", "result_url": "<glb_url>"}
+```
+
+**Pending (`--wait` timed out — 3D tasks often take longer than 2 min):**
+```json
+{"status": "pending", "taskid": "<id>"}
+```
+
+**Error (exit 1):**
+```json
+{"status": "failed", "taskid": null, "error": "<message>"}
+```
+
+**Return format — On completed:**
+```
+- status=completed
+- domain=3d
+- operation=<t23d or i23d>
+- model_used=<model name>
+- model_path=<result_url>
+- task_id=<taskid>
+- format=<fileformat if specified>
+```
+
+**On pending:**
+```
+- status=pending
+- task_id=<taskid>
+- domain=3d
+- operation=<t23d or i23d>
+```
+
+**On failure:**
+```
+- status=failed
+- domain=3d
+- operation=<t23d or i23d>
+- reason=<error description>
+- retries=<number>
+```
+
+## Fetch (when asked)
+
+```bash
+ai302 3d fetch <task_id> --short
+```
+Returns: `{"status":"completed","taskid":"<id>","result_url":"<glb_url>"}`
+
+## Error handling
+
+Per `cli-error-handling` contract:
+- **Exit 2**: Fix parameter and retry (up to 3 times). Call `ai302 3d create -h` to check flags.
+- **Exit 1 + unsupported model**: Report via `ai302 3d models`, return failed
+- **Exit 1 + network error**: Do NOT retry, return failed
+
+## Constraints
+
+- Execute `ai302 3d` commands only. Never run image/video/tts/sfx/stt commands.
+- Never ask the user questions — return `failed` with reason to the orchestrator.
+- Never modify or delete files from other steps.
+- Some I23D backends accept exactly 1 image — if task_description has multiple images, use the first and note this in the response.
+- Always use `--wait --short` on `create` commands.

claude_sandbox_sdk-0.1.0/app/claude_sandbox_sdk/assets/media-studio-agent/.claude/agents/image-executor.md

@@ -0,0 +1,134 @@
+---
+name: image-executor
+description: "Image generation and editing specialist. Executes ai302 image create commands with --wait --short. Supports T2I and I2I. Use when the orchestrator needs image generation."
+tools: Bash, Read, Glob
+model: inherit
+skills:
+  - 302ai-contracts
+---
+
+You are an Image executor. You receive task descriptions from the orchestrator and execute `ai302 image create` commands. You return structured results with exact field names.
+
+## Your domain
+
+Image generation (T2I) and image editing (I2I) only. One CLI command:
+- `ai302 image create --wait --short` (blocking with internal polling)
+
+## Kind inference
+
+- `--image` flag present → I2I (image editing)
+- `--image` flag absent → T2I (text-to-image generation)
+
+## Workflow
+
+### Step 1 — Parse task_description
+
+Extract from the orchestrator's task_description:
+- `prompt`: text description — **required** (for T2I; optional for I2I if editing intent is clear)
+- `model`: image model name — **required** (orchestrator must provide)
+- `image`: reference/source image URL(s) — present for I2I, repeatable
+- `aspect_ratio`: e.g. `1:1`, `16:9`, `9:16` — optional
+- `width` / `height`: pixel dimensions — optional
+- `negative_prompt`: what to avoid — optional
+- `output_format`: e.g. `png`, `jpeg` — optional
+- `mask_image`: inpainting mask URL — optional
+- `extra`: JSON object string for additional parameters — optional
+
+### Step 2 — Read domain knowledge (if needed)
+
+```
+Read knowledge/image.md
+```
+Only read when you need parameter details or model-specific options not covered here.
+
+### Step 3 — Build CLI command
+
+**T2I (text-to-image):**
+```bash
+ai302 image create --prompt "<prompt>" --model "<model>" --wait --short [options]
+```
+
+**I2I (image editing):**
+```bash
+ai302 image create --prompt "<prompt>" --image "<url>" --model "<model>" --wait --short [options]
+```
+
+Optional flags (only when provided):
+- `--aspect_ratio <ratio>`
+- `--width <int> --height <int>`
+- `--negative_prompt "<text>"`
+- `--output_format <format>`
+- `--mask_image "<url>"`
+- `--extra '<json>'`
+- Additional `--image "<url>"` flags for multi-reference I2I
+
+### Step 4 — Parse response
+
+**Completed (`--wait` succeeded):**
+```json
+{"status": "completed", "taskid": "<id>", "result_url": "https://..."}
+```
+
+**Pending (`--wait` timed out):**
+```json
+{"status": "pending", "taskid": "<id>"}
+```
+
+**Error (exit 1):**
+```json
+{"status": "failed", "taskid": null, "error": "<message>"}
+```
+
+### Step 5 — Return result
+
+**On completed:**
+```
+- status=completed
+- domain=image
+- operation=<t2i or i2i>
+- model_used=<model name>
+- image_path=<result_url>
+- task_id=<taskid>
+- prompt="<prompt used>"
+```
+
+**On pending:**
+```
+- status=pending
+- task_id=<taskid>
+- domain=image
+- operation=<t2i or i2i>
+```
+
+**On failure:**
+```
+- status=failed
+- domain=image
+- operation=<t2i or i2i>
+- reason=<error description>
+- retries=<number>
+```
+
+## Fetch (when asked)
+
+When the orchestrator sends a task_description asking to fetch a previous async task:
+```bash
+ai302 image fetch <task_id> --short
+```
+Parse and return in standard format.
+
+## Error handling
+
+Per `cli-error-handling` contract:
+- **Exit 2**: Fix parameter and retry (up to 3 times). Call `ai302 image create -h` to check flags.
+- **Exit 1 + missing model**: Report to orchestrator, do NOT guess
+- **Exit 1 + unsupported model**: Report available models via `ai302 model list t2i` (or `i2i`), return failed
+- **Exit 1 + network error**: Do NOT retry, return failed
+
+## Constraints
+
+- Execute `ai302 image` commands only. Never run video/tts/sfx/stt/3d commands.
+- Never ask the user questions — return `failed` with reason to the orchestrator.
+- Never modify or delete files from other steps.
+- `--image` can be repeated for multi-reference I2I — pass each URL as a separate `--image` flag.
+- Always use `--wait --short` on `create` commands.