chore: release version 0.5.0

This release includes the following changes:

New Features:
- Context Clear API: Added clear_async, get_clear_status, and synchronous clear
  methods with configurable timeout and state tracking
- SDK Telemetry: Session creation now records SDK version and release status
- Context Sync Enhancements: Introduced UploadMode and lifecycle enums for
  flexible synchronization policies
- Session Parameters: Made image_id optional in CreateSessionParams
- Browser Module: Added variables parameter to ActOptions for parameterized
  automation instructions
- Browser Module: Added use_vision parameter to ObserveOptions and ExtractOptions

API Changes:
- Added ClearContextRequest and ClearContextResponse models
- Enhanced ContextService with clear operations
- Updated ContextSync with new upload modes and lifecycle policies
- Added version_utils and _release modules for SDK versioning

Documentation:
- Updated API reference documentation for all modules
- Enhanced context usage guide and sync policy documentation
- Updated examples and guides to reflect new features
- Fixed documentation formatting issues

Testing:
- Added unit tests for Code, Command, FileSystem, ContextManager modules
- Added integration tests for context clear operations
- Added tests for recycle policy and file archive mode

Files Changed:
- 48 files modified, 1216 insertions(+), 511 deletions(-)
- New files: clear_context_request.py, clear_context_response.py,
  version_utils.py, _release.py, and multiple test files

Author: AgbAccount

.gitignore

@@ -133,9 +133,3 @@ dmypy.json
 .cursorrules
 CLAUDE.md
 .DS_Store
-
-# Dual repository management scripts and files
-scripts/dual-repo-management/
-sync-internal-to-external.sh
-sync-external-to-internal.sh
-DUAL_DIRECTORY_WORKFLOW.md

CHANGES.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.5.0] - 2025-11-20
+
+### New Features
+- **Context Clear API**: Added `clear_async`, `get_clear_status`, and synchronous `clear` with
+  configurable timeout, poll interval, and explicit state tracking.
+- **SDK Telemetry**: Session creation now records SDK version and release status, with explicit
+  release flagging injected during the official build process.
+- **Context Sync Enhancements**: Introduced `UploadMode` and lifecycle enums for more flexible
+  synchronization policies.
+- **Session Parameters**: Enforced `image_id` as a required field in `CreateSessionParams`,
+  improving validation and error messaging.
+- **Testing Framework**: Expanded unit tests to cover Code, Command, FileSystem, ContextManager,
+  SessionParams, response models, and context clear flows.
+
+### Bug Fixes
+- Added `error_message` propagation to `ContextSyncResult`, ensuring API failures surface in sync
+  results.
+- Aligned sample code and tests to use valid `image_id` values and consistent data paths, fixing
+  persistence-related flakes.
+
+### Documentation
+- Updated context usage guide, sync policy docs, API references, and data persistence examples to
+  reflect the new features.
+
+### Testing & CI
+- Added a RecyclePolicy integration test and tightened context sync test coverage, including path
+  uniqueness checks.
+- CI now runs unit tests by default, installs pytest automatically, and includes pipeline
+  optimizations plus master-branch triggers.
+
+
 ## [0.4.0] - 2025-10-31
 
 ### New Features

agb/__init__.py

@@ -5,7 +5,7 @@
 from .session_params import CreateSessionParams
 from .context import Context, ContextService, ContextResult, ContextListResult
 from .context_manager import ContextManager, ContextStatusData, ContextInfoResult, ContextSyncResult
-from .context_sync import ContextSync, SyncPolicy, UploadPolicy, DownloadPolicy, DeletePolicy, ExtractPolicy, UploadStrategy, DownloadStrategy
+from .context_sync import ContextSync, SyncPolicy, UploadPolicy, DownloadPolicy, DeletePolicy, ExtractPolicy, UploadStrategy, DownloadStrategy, UploadMode
 from .extension import ExtensionsService, ExtensionOption, Extension
 
 __all__ = [
@@ -14,5 +14,5 @@
     "Context", "ContextService", "ContextResult", "ContextListResult",
     "ContextManager", "ContextStatusData", "ContextInfoResult", "ContextSyncResult",
     "ContextSync", "SyncPolicy", "UploadPolicy", "DownloadPolicy", "DeletePolicy", "ExtractPolicy",
-    "UploadStrategy", "DownloadStrategy","ExtensionsService","ExtensionOption","Extension",
+    "UploadStrategy", "DownloadStrategy", "UploadMode", "ExtensionsService","ExtensionOption","Extension",
 ]

agb/_release.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+Release version flag.
+
+This file is modified during the CI/CD build process to set IS_RELEASE_VERSION = True
+for official releases.
+"""
+
+IS_RELEASE_VERSION = False
+

agb/agb.py

@@ -15,16 +15,15 @@
     CreateSessionResponse,
     CreateMcpSessionRequestPersistenceDataList,
     GetSessionRequest,
-    GetSessionResponse,
     ListSessionRequest,
-    ListSessionResponse,
 )
 from agb.config import Config, load_config
 from agb.model.response import DeleteResult, SessionResult, GetSessionResult, GetSessionData, SessionListResult
 from agb.session import BaseSession, Session
 from agb.session_params import CreateSessionParams
 from agb.context import ContextService
 from agb.logger import get_logger, log_operation_start, log_operation_success, log_warning
+from agb.version_utils import get_sdk_version, is_release_version
 
 logger = get_logger(__name__)
 
@@ -82,18 +81,43 @@ def create(self, params: Optional[CreateSessionParams] = None) -> SessionResult:
         """
         try:
             if params is None:
-                params = CreateSessionParams()
+                error_msg = "params is required and cannot be None"
+                logger.error(error_msg)
+                return SessionResult(
+                    request_id="",
+                    success=False,
+                    error_message=error_msg,
+                )
 
-            request = CreateSessionRequest(authorization=f"Bearer {self.api_key}")
+            # Validate image_id is required
+            if not params.image_id or (isinstance(params.image_id, str) and not params.image_id.strip()):
+                error_msg = "image_id is required and cannot be empty or None"
+                logger.error(error_msg)
+                return SessionResult(
+                    request_id="",
+                    success=False,
+                    error_message=error_msg,
+                )
 
-            if params.image_id:
-                request.image_id = params.image_id
+            request = CreateSessionRequest(authorization=f"Bearer {self.api_key}")
+            request.image_id = params.image_id
 
-             # Add labels if provided
+            # Add labels if provided
             if params.labels:
                 # Convert labels to JSON string
                 request.labels = json.dumps(params.labels)
 
+            # Add SDK stats for telemetry
+            sdk_version = get_sdk_version()
+            is_release = is_release_version()
+            sdk_stats = {
+                "source": "sdk",
+                "sdk_language": "python",
+                "sdk_version": sdk_version,
+                "is_release": is_release
+            }
+            request.sdk_stats = sdk_stats
+
             # Flag to indicate if we need to wait for context synchronization
             needs_context_sync = False
 

agb/api/client.py

@@ -39,6 +39,8 @@
     ModifyContextResponse,
     DeleteContextRequest,
     DeleteContextResponse,
+    ClearContextRequest,
+    ClearContextResponse,
     SyncContextRequest,
     SyncContextResponse,
     GetContextInfoRequest,
@@ -407,6 +409,23 @@ def delete_context(self, request: DeleteContextRequest) -> DeleteContextResponse
             # Always close the HTTP client to release resources
             http_client.close()
 
+    def clear_context(self, request: ClearContextRequest) -> ClearContextResponse:
+        """
+        Clear context using HTTP client
+        """
+        if not request.authorization:
+            raise ValueError("authorization is required")
+
+        # Get HTTP client and make request directly with the input request
+        http_client = self._get_http_client(request.authorization)
+
+        try:
+            response = http_client.clear_context(request)
+            return response
+        finally:
+            # Always close the HTTP client to release resources
+            http_client.close()
+
     def sync_context(self, request: SyncContextRequest) -> SyncContextResponse:
         """
         Sync context using HTTP client

agb/api/http_client.py

@@ -45,6 +45,8 @@
 from .models.modify_context_response import ModifyContextResponse
 from .models.delete_context_request import DeleteContextRequest
 from .models.delete_context_response import DeleteContextResponse
+from .models.clear_context_request import ClearContextRequest
+from .models.clear_context_response import ClearContextResponse
 from .models.sync_context_request import SyncContextRequest
 from .models.sync_context_response import SyncContextResponse
 from .models.get_context_info_request import GetContextInfoRequest
@@ -906,6 +908,37 @@ def delete_context(self, request: DeleteContextRequest) -> DeleteContextResponse
         # Return structured response object
         return DeleteContextResponse.from_http_response(response_dict)
 
+    def clear_context(self, request: ClearContextRequest) -> ClearContextResponse:
+        """
+        HTTP request interface for clearing context
+
+        Args:
+            request (ClearContextRequest): Request object for clearing context
+
+        Returns:
+            ClearContextResponse: Structured response object
+        """
+        # Build request headers
+        headers: Dict[str, str] = {}
+
+        # Build query parameters
+        params = request.get_params()
+
+        # Build request body
+        body = request.get_body()
+
+        # Call _make_request
+        response_dict = self._make_request(
+            method="POST",
+            endpoint="/sdk/ClearContext",
+            headers=headers,
+            params=params,
+            json_data=body,
+        )
+
+        # Return structured response object
+        return ClearContextResponse.from_http_response(response_dict)
+
     def sync_context(self, request: SyncContextRequest) -> SyncContextResponse:
         """
         HTTP request interface for syncing context

agb/api/models/__init__.py

@@ -34,6 +34,8 @@
 from .modify_context_response import ModifyContextResponse
 from .delete_context_request import DeleteContextRequest
 from .delete_context_response import DeleteContextResponse
+from .clear_context_request import ClearContextRequest
+from .clear_context_response import ClearContextResponse
 from .sync_context_request import SyncContextRequest
 from .sync_context_response import SyncContextResponse
 from .get_context_info_request import GetContextInfoRequest
@@ -80,6 +82,8 @@
     "ModifyContextResponse",
     "DeleteContextRequest",
     "DeleteContextResponse",
+    "ClearContextRequest",
+    "ClearContextResponse",
     "SyncContextRequest",
     "SyncContextResponse",
     "GetContextInfoRequest",

agb/api/models/clear_context_request.py

@@ -0,0 +1,32 @@
+from typing import Optional
+
+
+class ClearContextRequest:
+    """Request model for clearing a context."""
+
+    def __init__(
+        self,
+        authorization: str = "",
+        id: str = "",
+    ):
+        """
+        Initialize ClearContextRequest.
+
+        Args:
+            authorization (str): Authorization token.
+            id (str): ID of the context to clear.
+        """
+        self.authorization = authorization
+        self.id = id
+
+    def get_params(self) -> dict:
+        """Get the query parameters as a dictionary."""
+        params = {}
+        if self.id:
+            params["id"] = self.id
+        return params
+
+    def get_body(self) -> dict:
+        """Get the request body as a dictionary."""
+        return {}
+

agb/api/models/clear_context_response.py

@@ -0,0 +1,79 @@
+"""
+Clear context response model
+"""
+
+from typing import Any, Dict, Optional
+
+
+class ClearContextResponse:
+    """Structured response object for clear context operation"""
+
+    def __init__(
+        self,
+        status_code: int = 0,
+        url: str = "",
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ):
+        """
+        Initialize ClearContextResponse
+
+        Args:
+            status_code (int): HTTP status code
+            url (str): Request URL
+            headers (Dict[str, str]): Response headers
+            json_data (Dict[str, Any]): JSON response data
+            request_id (str): Request ID
+        """
+        self.status_code = status_code
+        self.url = url
+        self.headers = headers or {}
+        self.json_data = json_data or {}
+        self.request_id = request_id
+
+        if json_data:
+            self.api_success = json_data.get("success", False)
+            self.code = json_data.get("code", "")
+            self.http_status_code = json_data.get("httpStatusCode", "")
+            self.message = json_data.get("message", "")
+        else:
+            self.api_success = False
+            self.code = None
+            self.http_status_code = None
+            self.message = ""
+
+    @classmethod
+    def from_http_response(cls, response_dict: Dict[str, Any]) -> "ClearContextResponse":
+        """
+        Create ClearContextResponse from HTTP client returned dictionary
+
+        Args:
+            response_dict: Dictionary returned by HTTP client
+
+        Returns:
+            ClearContextResponse: Structured response object
+        """
+        return cls(
+            status_code=response_dict.get("status_code", 0),
+            url=response_dict.get("url", ""),
+            headers=response_dict.get("headers", {}),
+            json_data=response_dict.get("json"),
+            request_id=response_dict.get("request_id")
+            or (
+                response_dict.get("json", {}).get("requestId")
+                if response_dict.get("json")
+                else None
+            ),
+        )
+
+    def is_successful(self) -> bool:
+        """Check if the operation was successful"""
+        return self.status_code == 200 and self.api_success
+
+    def get_error_message(self) -> str:
+        """Get error message if operation failed"""
+        if not self.is_successful():
+            return self.message or f"HTTP {self.status_code} error"
+        return ""
+