release: v0.11.0 - TypeScript SDK, getCdpLink, session lifecycle, docs restructure

Breaking:
- listMcpTools (Python): imageId now required (no silent default)

Features:
- TypeScript SDK: full client (Session, Code, FileSystem, Browser, Computer, etc.)
- getCdpLink API (Python + TypeScript); Browser get_endpoint_url uses it
- Session lifecycle: idle release timeout, refresh idle (keep-alive), resource_url 30min
- BrowserAgent (TS): act, observe, extract, navigate; BrowserFingerprintGenerator
- Python: call_mcp_tool in BaseService; Session._base_service
- API reference: docs/api-reference/python/ + typescript/; Session docs split

Enhancements:
- FileSystem: FileInfo, FileChangeEvent, read bytes, write create_new, watchDir AbortSignal
- Computer: MouseButton.DOUBLE_LEFT, drag(button); CursorPosition/ScreenSize; ignore_system_app
- TS: requestId/getters, toJSON() for circular refs; Playwright-only screenshot
- Project: Python SDK under python/; root README for Python + TypeScript

Fixes:
- MCP screenshot: extract type=image content; Extension OSS 403 (fetch); getCdpLink body/header
- Docs: VitePress generics, dead links; CI path/subshell fixes; mypy/tsup

Docs: quickstart, context, session lifecycle/info/labels/list/mcp-tools; browser-type, captcha, proxy
Made-with: Cursor

Author: AgbAccount

.gitignore

@@ -35,8 +35,12 @@ MANIFEST
 pip-log.txt
 pip-delete-this-directory.txt
 
+# Dev temporary files (generated analysis, comparison docs, etc.)
+docs/dev/
+
 # Unit test / coverage reports
 htmlcov/
+coverage/
 .tox/
 .nox/
 .coverage
@@ -136,3 +140,8 @@ CLAUDE.md
 
 # uv lockfile (only used when using uv; project uses venv)
 uv.lock
+
+# Node.js / TypeScript
+node_modules/
+*.tsbuildinfo
+.history/

CHANGES.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.11.0] - 2026-03-16
+
+### Breaking Changes
+
+- **listMcpTools (Python)**: Explicit `imageId` is now required (no silent default). Callers must pass `imageId` when listing MCP tools.
+
+### New Features
+
+- **TypeScript SDK**: Full TypeScript SDK for AGB (client, Session, Config, API layer, Command, Code, FileSystem, Browser, Computer, Extension, Context, exceptions, logger). API models split into 51 separate files.
+- **getCdpLink**: New API in Python and TypeScript; sessionId as query parameter. Browser `get_endpoint_url` uses getCdpLink in Python.
+- **BrowserAgent (TypeScript)**: `act`, `observe`, `extract`, `navigate`; async variants with time-based timeout; BrowserFingerprintGenerator and FingerprintFormat.
+- **Session lifecycle**: Idle release timeout (configurable); refresh session idle time API (keep-alive). Docs for lifecycle, keep-alive, and resource_url validity (30 min).
+- **Python**: `call_mcp_tool` delegated to BaseService to remove duplication; Session uses `_base_service`.
+- **Module parity (TypeScript)**: FileSystem upload/download via pre-signed URLs, `transferPath`, `watchDir`; Computer.Window fullscreen/focusMode; Computer.App `stopByCmd`/`getVisible`; Browser `getOption`/`isInitialized`; Session `getAgb()`; new file-transfer module for OSS and context sync.
+- **CI/CD**: TypeScript official release pipeline and script; npm build/publish pipeline; internal tnpm test publish; publish npm test to tnpm when patch is merged.
+- **Documentation**: Single root README (Python + TypeScript quick start, docs, development); website and Discord URLs; TypeScript code examples in VitePress code-group tabs; API reference merged into `docs/api-reference` with python/ and typescript/; Session docs split (lifecycle, info, labels, list, mcp-tools); Context expanded (concepts, best practices, FAQ); call-for-use and captcha docs.
+
+### Enhancements
+
+- **Filesystem (Python)**: FileInfo type; FileChangeEvent eventType/pathType; readFile with `{ format: "bytes" }`; writeFile `create_new` mode; watchDirectory with AbortSignal; sync fallback (awaitSync); waitForTask uses `res.items ?? res.contextStatusData`; OSS cleanup after upload/download. Unit tests aligned to DEFAULT_CHUNK_SIZE 50KB.
+- **Computer (Python/TS)**: MouseButton.DOUBLE_LEFT, drag(button); getPosition/getSize return CursorPosition/ScreenSize; get_installed_apps uses `ignore_system_app`. Browser: BrowserProxy managed type (user_id, isp, country, province, city).
+- **TypeScript**: Response models gained requestId and field parsing; getters (getTotalCount, getExpireTime, etc.); `toJSON()` on Session, AGB, BaseService, ContextService, ContextManager, Computer to avoid circular serialization; Browser screenshot Playwright-only (MCP screenshot removed); interface signatures aligned with Python (Keyboard press/release, App start/listInstalled, FileSystem progressCallback, Extension cleanup). `AGB.get()` returns `session: null` when session is deleted or missing (typed as `Session | null`).
+- **Project structure**: Python SDK moved under `python/` (agb/, tests/, pyproject.toml, etc.); CI, scripts, root README updated.
+
+### Bug Fixes
+
+- **MCP screenshot**: CallMcpToolResponse now extracts `type="image"` content when no text (screenshot tool returns image).
+- **Extension upload (TS)**: Use `fetch` instead of axios to fix 403 OSS upload.
+- **getCdpLink**: TypeScript sends empty JSON body and capitalized Authorization header; Python/TS tests fail explicitly instead of silent skip.
+- **Extension upload message (TS)**: Use `errorMessage` instead of `url` on failure.
+- **tsup (TS)**: Externalize playwright to fix ESM/CJS build (optional runtime dependency).
+- **Docs**: VitePress angle bracket escaping for TS generics; dead links fixed (tutorial depth, Related Resources, quickstart, browser links); tutorial link path generation for absolute-style paths; CI copy logic so api-reference/python/ does not get nested subdirs.
+- **Python**: mypy fixes (GetCdpLinkResponse, Browser/FileSystem __init__, Optional dicts, FileError duplicate, logging params, browser agent extract return types).
+- **CI**: Subshell `(cd python && ...)` to prevent path duplication; job outputs for pass/fail; summary decoupled from test jobs; correct image ID and AGB_ENDPOINT for TS integration tests; continue-on-error to avoid fast-fail cascade; clone retries and git HTTP tuning for push-docs-to-github.
+
+### Documentation, Testing & Chore
+
+- **Docs**: TypeScript API docs auto-generation in pipeline (TypeDoc); doc-metadata and computer overview generation (sub-modules before container, exclude_methods). Removed session best-practices.md, troubleshooting.md; keep-alive folded into lifecycle.
+- **Testing**: TypeScript unit tests (session, base-service, logger, api-response, command, code, filesystem, computer, browser, extension, context, context-manager, api models, http-client, client, file-transfer, agb, BrowserAgent, fingerprint); integration tests (all modules, browser, computer, file transfer, watchDir, MCP, advanced suites). Python unit coverage to ~83% (logger, code, computer submodules, file_system, context_manager); getCdpLink integration tests. Pre env uses agb-code-space-2; CICD script names optimized.
+- **Chore**: Removed unused session management methods and models; trimmed keep-alive use-case examples; docs/dev/ in .gitignore; code formatting (agb, browser). Pause and resume was added then removed in this cycle and is not part of the release.
+
 ## [0.10.0] - 2026-02-09
 
 This release focuses on **API Naming Simplification Phase 2** in the Computer module, the new **policy_id** parameter for session creation, and **OpenClaw examples** for Slack, Discord, and Telegram.

README.md

@@ -5,6 +5,8 @@
   </a>
 </h4>
 
+---
+
 ## 🔥 Moltbot (formerly Clawdbot) Quick Deployment
 
 You can use AGB SDK to spin up a prebuilt Moltbot cloud desktop in minutes, then open the Moltbot console inside the desktop browser.
@@ -17,25 +19,34 @@ You can use AGB SDK to spin up a prebuilt Moltbot cloud desktop in minutes, then
 
 ---
 
-AGB Python SDK provides a convenient way to interact with the AGB cloud service.
+AGB Cloud SDK provides client libraries for interacting with the AGB cloud service.
 
 ## Features
 
 - Create and manage sessions in the AGB cloud environment
-- Access session information
 - Work with file system, command execution, and code execution modules
 - Browser automation with AI-powered natural language operations
-- Advanced browser configuration (stealth mode, proxies, fingerprinting)
-- Structured data extraction from web pages
+- Persistent context management with sync policies
+
+### 🎯 Scenario-Based Features
+- **Computer Use** - Linux computer control (mouse, keyboard, window, application, screen)
+- **Browser Use** - Web automation, scraping, and browser control
+- **CodeSpace** - Code execution and development environment
 
 ## Installation
 
 ```bash
+# Python
 pip install agbcloud-sdk
+
+# TypeScript
+npm install agbcloud-sdk
 ```
 
 ## Quick Start
 
+### Python
+
 ```python
 from agb import AGB
 from agb.session_params import CreateSessionParams
@@ -71,6 +82,41 @@ else:
     print(f"Failed to create session: {result.error_message}")
 ```
 
+### TypeScript
+
+```typescript
+import { AGB, CreateSessionParams } from "agbcloud-sdk";
+
+// Initialize AGB with your API key
+const agb = new AGB({ apiKey: "your-api-key" });
+
+// Create a session
+const params = new CreateSessionParams({ imageId: "agb-code-space-1" });
+const result = await agb.create(params);
+
+if (result.success && result.session) {
+  const session = result.session;
+
+  // Execute Python code
+  const codeResult = await session.code.run("print('Hello AGB!')", "python");
+  console.log(codeResult.results[0]?.text);
+
+  // Execute shell command
+  const cmdResult = await session.command.execute("ls -la");
+  console.log(cmdResult.stdout);
+
+  // Work with files
+  await session.file.writeFile("/tmp/test.txt", "Hello World!");
+  const fileResult = await session.file.readFile("/tmp/test.txt");
+  console.log(fileResult.content);
+
+  // Clean up
+  await agb.delete(session);
+} else {
+  console.error(`Failed to create session: ${result.errorMessage}`);
+}
+```
+
 ## Documentation
 
 For comprehensive documentation, guides, and examples, visit:
@@ -84,29 +130,33 @@ For comprehensive documentation, guides, and examples, visit:
 
 ## Development
 
-### Prerequisites
+### Python
 
-- Python 3.10 or higher
-- pip
+```bash
+cd python
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e ".[dev,test]"
+```
+
+### TypeScript
 
-### Setup
+```bash
+cd typescript
+npm install
+npm run build
+npm test
+```
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/agbcloud/agbcloud-sdk.git
-   cd agbcloud-sdk
-   ```
+## Get Help
+- [GitHub Issues](https://github.com/agbcloud/agbcloud-sdk/issues)
 
-2. Create a virtual environment:
-   ```bash
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-   ```
+## Contact
+Welcome to visit our product website and join our community!
 
-3. Install dependencies:
-   ```bash
-   pip install -e ."[dev,test]"
-   ```
+- **AGB Product Website**: [https://agb.cloud/](https://agb.cloud/)
+- **AGB Console**: [https://agb.cloud/console/overview](https://agb.cloud/console/overview)
+- **Discord Community**: [Join on Discord](https://discord.gg/WQ2EHJxhy7)
 
 ## License
 

docs/README.md

@@ -25,27 +25,44 @@ Understanding the lifecycle of a session is crucial for resource management and
 3.  **Timeout (Auto-Shutdown)**: Sessions are automatically reclaimed after **30 minutes** of inactivity by default to prevent runaway costs.
 4.  **Deletion**: Explicitly deleting a session releases resources immediately.
 
-```python
+::: code-group
+
+```python [Python]
 from agb import AGB
 from agb.session_params import CreateSessionParams
 
 agb = AGB()
 
-# Example: Create a Code Execution Session
 code_params = CreateSessionParams(image_id="agb-code-space-1")
 result = agb.create(code_params)
 
 if result.success:
     code_session = result.session
-
     # ... perform operations ...
-
-    # Clean up
     agb.delete(code_session)
 else:
     print(f"Failed to create session: {result.error_message}")
 ```
 
+```typescript [TypeScript]
+import { AGB, CreateSessionParams } from "agbcloud-sdk";
+
+const agb = new AGB();
+
+const codeParams = new CreateSessionParams({ imageId: "agb-code-space-1" });
+const result = await agb.create(codeParams);
+
+if (result.success && result.session) {
+  const codeSession = result.session;
+  // ... perform operations ...
+  await agb.delete(codeSession);
+} else {
+  console.error("Failed to create session:", result.errorMessage);
+}
+```
+
+:::
+
 ### Key Capabilities
 
 -   **Labels**: Tag sessions with custom key-value pairs (e.g., `user_id`, `env`) for organization and filtering.

docs/api-key.md

@@ -15,9 +15,9 @@ There are two main ways to provide your API key:
 
 ## Examples
 
-### Python
+::: code-group
 
-```python
+```python [Python]
 # Method 1: Direct initialization with API key
 api_key = "your_api_key_here"
 agb = AGB(api_key=api_key)
@@ -28,6 +28,18 @@ agb = AGB(api_key=api_key)
 agb = AGB()
 ```
 
+```typescript [TypeScript]
+// Method 1: Direct initialization with API key
+const agb = new AGB({ apiKey: "your_api_key_here" });
+
+// Method 2: Using environment variable
+// First, set the environment variable:
+// export AGB_API_KEY=your_api_key_here
+const agb2 = new AGB();
+```
+
+:::
+
 ## Best Practices
 
 1. **Environment Variables**: For production applications, it's recommended to use environment variables rather than hardcoding API keys in your code.

docs/api-reference/README.md

@@ -1,35 +1,6 @@
-# AGB Python SDK API Reference
+# AGB SDK API Reference
 
-This directory is generated. Run `python scripts/generate_api_docs.py` to refresh it.
+API reference documentation for the AGB SDK, generated from source code.
 
-## Core
-
-- `agb.md` – AGB
-- `session.md` – Session
-
-## Capabilities
-
-- `capabilities/shell_commands.md` – Command
-- `capabilities/file_system.md` – File System
-- `capabilities/code_execution.md` – Code
-- `capabilities/browser.md` – Browser
-- `capabilities/computer.md` – Computer
-
-## Data Context
-
-- `data_context/context.md` – Context
-- `data_context/context_manager.md` – Context Manager
-- `data_context/synchronization.md` – Synchronization
-
-## Reference
-
-- `reference/logging.md` – Logging
-- `reference/extensions.md` – Extension
-- `reference/configurations.md` – Configurations
-- `reference/exceptions.md` – Exceptions
-
-## Reference & Types
-
-- `reference/types.md` – Response Types & Schemas
-- `reference/exceptions.md` – SDK Exceptions
-- `reference/configurations.md` – Configuration Parameters
+- **[Python SDK API Reference](python/README.md)** – Generated from Python docstrings. Run `python scripts/generate_api_docs.py` to refresh.
+- **[TypeScript SDK API Reference](typescript/README.md)** – Generated with TypeDoc. Run `npm run docs:generate` from the `typescript` directory to refresh.

docs/api-reference/python/README.md

@@ -0,0 +1,35 @@
+# AGB Python SDK API Reference
+
+This directory is generated. Run `python scripts/generate_api_docs.py` to refresh it.
+
+## Core
+
+- `agb.md` – AGB
+- `session.md` – Session
+
+## Capabilities
+
+- `capabilities/shell_commands.md` – Command
+- `capabilities/file_system.md` – File System
+- `capabilities/code_execution.md` – Code
+- `capabilities/browser.md` – Browser
+- `capabilities/computer.md` – Computer
+
+## Data Context
+
+- `data_context/context.md` – Context
+- `data_context/context_manager.md` – Context Manager
+- `data_context/synchronization.md` – Synchronization
+
+## Reference
+
+- `reference/logging.md` – Logging
+- `reference/extensions.md` – Extension
+- `reference/configurations.md` – Configurations
+- `reference/exceptions.md` – Exceptions
+
+## Reference & Types
+
+- `reference/types.md` – Response Types & Schemas
+- `reference/exceptions.md` – SDK Exceptions
+- `reference/configurations.md` – Configuration Parameters

docs/api-reference/agb.md docs/api-reference/python/agb.mddocs/api-reference/agb.md renamed to docs/api-reference/python/agb.md

@@ -2,7 +2,7 @@
 
 ## Related Tutorial
 
-- [Quick Start Guide](../quickstart.md) - Get started with the AGB Python SDK
+- [Quick Start Guide](../../quickstart.md) - Get started with the AGB Python SDK
 
 ## Overview