release: sync v0.12.0 from internal repository

Author: AgbAccount

.github/workflows/release.yml

@@ -0,0 +1,60 @@
+# Automatically create a GitHub Release when a version tag is pushed.
+# Extracts the changelog section for the tagged version from CHANGES.md.
+
+name: Create Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Releasing: $TAG (version $VERSION)"
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+
+          # Extract the section between ## [VERSION] and the next ## [
+          BODY=$(awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (found) exit
+              if (index($0, "[" ver "]")) { found=1; next }
+            }
+            found { print }
+          ' CHANGES.md)
+
+          if [ -z "$BODY" ]; then
+            BODY="Release ${{ steps.version.outputs.tag }}"
+            echo "Warning: No changelog entry found for version $VERSION"
+          fi
+
+          # Write to file to preserve newlines
+          echo "$BODY" > /tmp/release-body.md
+          echo "body_file=/tmp/release-body.md" >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          name: ${{ steps.version.outputs.tag }}
+          body_path: ${{ steps.changelog.outputs.body_file }}
+          draft: false
+          prerelease: false

CHANGES.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.12.0] - 2026-04-07
+
+### New Features
+
+- **WebSocket**: New websocket client module (`ws`) with integration tests; session-level websocket client initialization and cleanup with improved logging on deletion.
+- **MCP Tools**: Add support for MCP tools in session — tool list parsing, `callMcpTool` routing, session URL handling, and additional session fields.
+- **Screenshot (Python)**: `beta_take_screenshot` method in Screen module with fixed import order.
+- **Screenshot (TypeScript)**: Sync `betaTakeScreenshot` API with unit and integration tests.
+- **Execution Context**: New documentation for execution context module.
+
+### Enhancements
+
+- **MCP Routing**: MCP tool invocation smart routing pushed down to `BaseService`, aligning Python and TypeScript implementations.
+- **TypeScript Exceptions**: Refactor exception classes with factory functions to eliminate duplicate code.
+- **TypeScript**: Remove `enableBrowserReplay` feature; add union types for tool list and improve imports handling.
+- **FileSystem Monitoring**: Enhance directory monitoring logic with ready event, baseline establishment flag, and execution error handling.
+- **WebSocket**: Update ws exceptions with extra params; simplify ws client logic and error creation pattern.
+- **API Consistency**: Rename `run_code` to `_run_code` and update related methods and docs across modules; update method calls for consistency across Python and TypeScript.
+- **MIME Handling**: Improve MIME type handling and add default stream target.
+- **Data Retrieval**: Improve data retrieval logic and add helper functions for type safety.
+- **Testing**: Update session creation params and image ID for testing consistency across languages.
+
+### Bug Fixes
+
+- **Dependencies**: `websockets` is now a required dependency (was missing from install_requires).
+- **Screenshot**: Fix `screen.beta_take_screenshot` integration test error; fix unit and integration test errors in code and screenshot modules.
+- **TypeScript**: Add `callMcpTool` to mock sessions for `SessionLike` interface compliance; fix API doc generation error; add ws dependency and improve logging in TypeScript modules.
+- **Tool List**: Handle empty tool list and improve content check logic.
+- **Timeout**: Add timeout parameters to future results in sync client; improve exception handling in TypeScript modules.
+- **FileSystem**: Correct parameter name for stop event in directory monitoring example.
+- **Scripts**: Remove wrong option in CI script.
+
+### Documentation, Testing & Chore
+
+- **Release Automation**: Add release SOP, automation scripts, unified CI release pipeline, and GitHub Actions auto-release workflow.
+- **Docs**: Add real-time streaming and websocket documentation; use "remote browser" wording and document stealth option in TypeScript API.
+- **Docs Fixes**: Fix documentation issues found during review (dead links, formatting).
+- **Testing**: Add websockets dependency for testing.
+- **API Docs**: Auto-generated API reference documentation updated.
+- **CI/CD**: Add pipeline for SDK sync to GitHub; unified release pipeline, changelog generation, version bump, and doc-check automation scripts.
+
 ## [0.11.0] - 2026-03-16
 
 ### Breaking Changes

docs/api-reference/python/capabilities/code_execution.md

@@ -16,6 +16,22 @@ It supports multiple programming languages including Python, JavaScript, and mor
 
 
 
+#### LANGUAGE\_ALIASES
+
+```python
+LANGUAGE_ALIASES = {
+    "py": "python",
+    "python3": "python",
+    "js": "javascript",
+    "node" ...
+```
+
+#### SUPPORTED\_LANGUAGES
+
+```python
+SUPPORTED_LANGUAGES = {"python", "javascript", "java", "r"}
+```
+
 ## Code
 
 ```python
@@ -27,33 +43,45 @@ Handles code execution operations in the AGB cloud environment.
 ### run
 
 ```python
-def run(code: str,
-        language: str,
-        timeout_s: int = 60) -> EnhancedCodeExecutionResult
+def run(
+    code: str,
+    language: str,
+    timeout_s: int = 60,
+    stream_beta: bool = False,
+    on_stdout: Optional[Callable[[str], None]] = None,
+    on_stderr: Optional[Callable[[str], None]] = None,
+    on_error: Optional[Callable[[Any], None]] = None
+) -> EnhancedCodeExecutionResult
 ```
 
 Execute code in the specified language with a timeout.
 
+This is the primary public method for code execution. For real-time
+streaming output, set stream_beta=True and provide callback functions.
+
 **Arguments**:
 
-- `code` _str_ - The code to execute.
-- `language` _str_ - The programming language of the code. Supported languages are:
-  'python', 'javascript', 'java', 'r'.
-- `timeout_s` _int_ - The timeout for the code execution in seconds. Default is 60s.
+    code: The code to execute.
+    language: The programming language of the code. Case-insensitive.
+  Supported values: 'python', 'javascript', 'r', 'java'.
+    Aliases: 'py' -> 'python', 'js'/'node' -> 'javascript'.
+    timeout_s: The timeout for the code execution in seconds. Default is 60s.
+    stream_beta: If True, use WebSocket streaming for real-time stdout/stderr
+  output. Requires the session to have a valid ws_url. Default is False.
+    on_stdout: Callback invoked with each stdout chunk during streaming.
+  Only used when stream_beta=True.
+    on_stderr: Callback invoked with each stderr chunk during streaming.
+  Only used when stream_beta=True.
+    on_error: Callback invoked when an error occurs during streaming.
+  Only used when stream_beta=True.
 
 
 **Returns**:
 
-    EnhancedCodeExecutionResult: Enhanced result object containing success status,
+    EnhancedCodeExecutionResult: Result object containing success status,
   execution results with rich format support (HTML, images, charts, etc.),
   logs, and error information if any.
 
-
-**Raises**:
-
-    CommandError: If the code execution fails or if an unsupported language is
-  specified.
-
 ## Best Practices
 
 1. Validate code syntax before execution

docs/api-reference/python/capabilities/computer.md

@@ -710,6 +710,42 @@ Gets the screen size and DPI scaling factor.
   - DPI scaling factor affects coordinate calculations on high-DPI displays
   - Use this to determine valid coordinate ranges for mouse operations
 
+### beta\_take\_screenshot
+
+```python
+def beta_take_screenshot(format: str = "png") -> ScreenshotResult
+```
+
+Takes a screenshot of the Computer and returns raw binary image data.
+
+This API uses the MCP tool `screenshot` (wuying_capture) and returns raw
+binary image data. The backend also returns the captured image dimensions
+(width/height in pixels), which are exposed on `ScreenshotResult.width`
+and `ScreenshotResult.height`. The backend metadata fields `type` and
+`mime_type` are exposed on `ScreenshotResult.type` and `ScreenshotResult.mime_type`.
+
+**Arguments**:
+
+    format: The desired image format (default: "png"). Supported: "png", "jpeg", "jpg".
+
+
+**Returns**:
+
+    ScreenshotResult: Object containing the screenshot image data (bytes) and metadata
+  including `type`, `mime_type`, `width`, and `height` when provided by the backend.
+
+
+**Raises**:
+
+    ScreenError: If screenshot fails or response cannot be decoded.
+    ValueError: If `format` is invalid.
+
+
+**Notes**:
+
+  This method only works in environments with link_url (e.g., Browser Use images).
+  For other environments, use `capture()` instead.
+
 Computer module main class - container for all computer automation controllers.
 
 ## Computer

docs/api-reference/python/capabilities/file_system.md

@@ -496,7 +496,12 @@ Watch a directory for file changes and call the callback function when changes o
 **Returns**:
 
     threading.Thread: The monitoring thread. Call thread.start() to begin monitoring.
-  Use the thread's stop_event attribute to stop monitoring.
+  The thread has two event attributes:
+
+  - ``stop_event`` – set this to stop monitoring.
+  - ``ready_event`` – wait on this after calling ``start()`` to
+  ensure the filesystem baseline has been established before
+  performing any file operations.
 
 ## Best Practices
 

docs/api-reference/python/reference/exceptions.md

@@ -79,6 +79,14 @@ class ClearanceTimeoutError(AGBError)
 
 Raised when the clearance task times out.
 
+## ScreenError
+
+```python
+class ScreenError(AGBError)
+```
+
+Raised for errors related to screen operations.
+
 ---
 
 *Documentation generated automatically from source code using pydoc-markdown.*

docs/api-reference/python/session.md

@@ -20,6 +20,18 @@ class Session()
 
 Session represents a session in the AGB cloud environment.
 
+### get\_link\_url
+
+```python
+def get_link_url() -> str
+```
+
+### get\_token
+
+```python
+def get_token() -> str
+```
+
 ### set\_labels
 
 ```python
@@ -183,6 +195,10 @@ def call_mcp_tool(tool_name: str,
 
 Call the specified MCP tool.
 
+This method intelligently routes the call to either:
+1. LinkUrl route (direct HTTP) - when link_url, token, and server_name are available
+2. Traditional API route - fallback method
+
 **Arguments**:
 
 - `tool_name` _str_ - Tool name (e.g., "tap", "get_ui_elements").