chore(release): v0.4.0-preview.1

test: separating integration tests for the CLI and SDK

.github/workflows/release-sdk.yml

@@ -0,0 +1,237 @@
+name: 'Release SDK'
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'The version to release (e.g., v0.1.11). Required for manual patch releases.'
+        required: false
+        type: 'string'
+      ref:
+        description: 'The branch or ref (full git sha) to release from.'
+        required: true
+        type: 'string'
+        default: 'main'
+      dry_run:
+        description: 'Run a dry-run of the release process; no branches, npm packages or GitHub releases will be created.'
+        required: true
+        type: 'boolean'
+        default: true
+      create_nightly_release:
+        description: 'Auto apply the nightly release tag, input version is ignored.'
+        required: false
+        type: 'boolean'
+        default: false
+      create_preview_release:
+        description: 'Auto apply the preview release tag, input version is ignored.'
+        required: false
+        type: 'boolean'
+        default: false
+      force_skip_tests:
+        description: 'Select to skip the "Run Tests" step in testing. Prod releases should run tests'
+        required: false
+        type: 'boolean'
+        default: false
+
+jobs:
+  release-sdk:
+    runs-on: 'ubuntu-latest'
+    environment:
+      name: 'production-release'
+      url: '${{ github.server_url }}/${{ github.repository }}/releases/tag/sdk-typescript-${{ steps.version.outputs.RELEASE_TAG }}'
+    if: |-
+      ${{ github.repository == 'QwenLM/qwen-code' }}
+    permissions:
+      contents: 'write'
+      packages: 'write'
+      id-token: 'write'
+      issues: 'write'
+    outputs:
+      RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ github.event.inputs.ref || github.sha }}'
+          fetch-depth: 0
+
+      - name: 'Set booleans for simplified logic'
+        env:
+          CREATE_NIGHTLY_RELEASE: '${{ github.event.inputs.create_nightly_release }}'
+          CREATE_PREVIEW_RELEASE: '${{ github.event.inputs.create_preview_release }}'
+          DRY_RUN_INPUT: '${{ github.event.inputs.dry_run }}'
+        id: 'vars'
+        run: |-
+          is_nightly="false"
+          if [[ "${CREATE_NIGHTLY_RELEASE}" == "true" ]]; then
+            is_nightly="true"
+          fi
+          echo "is_nightly=${is_nightly}" >> "${GITHUB_OUTPUT}"
+
+          is_preview="false"
+          if [[ "${CREATE_PREVIEW_RELEASE}" == "true" ]]; then
+            is_preview="true"
+          fi
+          echo "is_preview=${is_preview}" >> "${GITHUB_OUTPUT}"
+
+          is_dry_run="false"
+          if [[ "${DRY_RUN_INPUT}" == "true" ]]; then
+            is_dry_run="true"
+          fi
+          echo "is_dry_run=${is_dry_run}" >> "${GITHUB_OUTPUT}"
+
+      - name: 'Setup Node.js'
+        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: 'Install Dependencies'
+        run: |-
+          npm ci
+
+      - name: 'Get the version'
+        id: 'version'
+        run: |
+          VERSION_ARGS=()
+          if [[ "${IS_NIGHTLY}" == "true" ]]; then
+            VERSION_ARGS+=(--type=nightly)
+          elif [[ "${IS_PREVIEW}" == "true" ]]; then
+            VERSION_ARGS+=(--type=preview)
+            if [[ -n "${MANUAL_VERSION}" ]]; then
+              VERSION_ARGS+=("--preview_version_override=${MANUAL_VERSION}")
+            fi
+          else
+            VERSION_ARGS+=(--type=stable)
+            if [[ -n "${MANUAL_VERSION}" ]]; then
+              VERSION_ARGS+=("--stable_version_override=${MANUAL_VERSION}")
+            fi
+          fi
+
+          VERSION_JSON=$(node packages/sdk-typescript/scripts/get-release-version.js "${VERSION_ARGS[@]}")
+          echo "RELEASE_TAG=$(echo "$VERSION_JSON" | jq -r .releaseTag)" >> "$GITHUB_OUTPUT"
+          echo "RELEASE_VERSION=$(echo "$VERSION_JSON" | jq -r .releaseVersion)" >> "$GITHUB_OUTPUT"
+          echo "NPM_TAG=$(echo "$VERSION_JSON" | jq -r .npmTag)" >> "$GITHUB_OUTPUT"
+
+          echo "PREVIOUS_RELEASE_TAG=$(echo "$VERSION_JSON" | jq -r .previousReleaseTag)" >> "$GITHUB_OUTPUT"
+        env:
+          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          IS_NIGHTLY: '${{ steps.vars.outputs.is_nightly }}'
+          IS_PREVIEW: '${{ steps.vars.outputs.is_preview }}'
+          MANUAL_VERSION: '${{ inputs.version }}'
+
+      - name: 'Run Tests'
+        if: |-
+          ${{ github.event.inputs.force_skip_tests != 'true' }}
+        working-directory: 'packages/sdk-typescript'
+        run: |
+          npm run test:ci
+        env:
+          OPENAI_API_KEY: '${{ secrets.OPENAI_API_KEY }}'
+          OPENAI_BASE_URL: '${{ secrets.OPENAI_BASE_URL }}'
+          OPENAI_MODEL: '${{ secrets.OPENAI_MODEL }}'
+
+      - name: 'Build CLI for Integration Tests'
+        if: |-
+          ${{ github.event.inputs.force_skip_tests != 'true' }}
+        run: |
+          npm run build
+          npm run bundle
+
+      - name: 'Run SDK Integration Tests'
+        if: |-
+          ${{ github.event.inputs.force_skip_tests != 'true' }}
+        run: |
+          npm run test:integration:sdk:sandbox:none
+          npm run test:integration:sdk:sandbox:docker
+        env:
+          OPENAI_API_KEY: '${{ secrets.OPENAI_API_KEY }}'
+          OPENAI_BASE_URL: '${{ secrets.OPENAI_BASE_URL }}'
+          OPENAI_MODEL: '${{ secrets.OPENAI_MODEL }}'
+
+      - name: 'Configure Git User'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: 'Create and switch to a release branch'
+        id: 'release_branch'
+        env:
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+        run: |-
+          BRANCH_NAME="release/sdk-typescript/${RELEASE_TAG}"
+          git switch -c "${BRANCH_NAME}"
+          echo "BRANCH_NAME=${BRANCH_NAME}" >> "${GITHUB_OUTPUT}"
+
+      - name: 'Update package version'
+        working-directory: 'packages/sdk-typescript'
+        env:
+          RELEASE_VERSION: '${{ steps.version.outputs.RELEASE_VERSION }}'
+        run: |-
+          npm version "${RELEASE_VERSION}" --no-git-tag-version --allow-same-version
+
+      - name: 'Commit and Conditionally Push package version'
+        env:
+          BRANCH_NAME: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
+          IS_DRY_RUN: '${{ steps.vars.outputs.is_dry_run }}'
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+        run: |-
+          git add packages/sdk-typescript/package.json
+          if git diff --staged --quiet; then
+            echo "No version changes to commit"
+          else
+            git commit -m "chore(release): sdk-typescript ${RELEASE_TAG}"
+          fi
+          if [[ "${IS_DRY_RUN}" == "false" ]]; then
+            echo "Pushing release branch to remote..."
+            git push --set-upstream origin "${BRANCH_NAME}" --follow-tags
+          else
+            echo "Dry run enabled. Skipping push."
+          fi
+
+      - name: 'Build SDK'
+        working-directory: 'packages/sdk-typescript'
+        run: |-
+          npm run build
+
+      - name: 'Configure npm for publishing'
+        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@qwen-code'
+
+      - name: 'Publish @qwen-code/sdk'
+        working-directory: 'packages/sdk-typescript'
+        run: |-
+          npm publish --access public --tag=${{ steps.version.outputs.NPM_TAG }} ${{ steps.vars.outputs.is_dry_run == 'true' && '--dry-run' || '' }}
+        env:
+          NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
+
+      - name: 'Create GitHub Release and Tag'
+        if: |-
+          ${{ steps.vars.outputs.is_dry_run == 'false' }}
+        env:
+          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          RELEASE_BRANCH: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+          PREVIOUS_RELEASE_TAG: '${{ steps.version.outputs.PREVIOUS_RELEASE_TAG }}'
+        run: |-
+          gh release create "sdk-typescript-${RELEASE_TAG}" \
+            --target "$RELEASE_BRANCH" \
+            --title "SDK TypeScript Release ${RELEASE_TAG}" \
+            --notes-start-tag "sdk-typescript-${PREVIOUS_RELEASE_TAG}" \
+            --generate-notes
+
+      - name: 'Create Issue on Failure'
+        if: |-
+          ${{ failure() }}
+        env:
+          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          RELEASE_TAG: "${{ steps.version.outputs.RELEASE_TAG || 'N/A' }}"
+          DETAILS_URL: '${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+        run: |-
+          gh issue create \
+            --title "SDK Release Failed for ${RELEASE_TAG} on $(date +'%Y-%m-%d')" \
+            --body "The SDK release workflow failed. See the full run for details: ${DETAILS_URL}"

.vscode/launch.json

@@ -79,7 +79,6 @@
         "--",
         "-p",
         "${input:prompt}",
-        "-y",
         "--output-format",
         "stream-json"
       ],

docs/_meta.ts

@@ -1,14 +1,10 @@
 export default {
-  index: {
-    type: 'page',
-    display: 'hidden',
-  },
-  users: {
-    type: 'page',
-    title: 'User Guide',
-  },
-  developers: {
-    type: 'page',
-    title: 'Developer Guide',
-  },
+  index: 'Welcome to Qwen Code',
+  cli: 'CLI',
+  core: 'Core',
+  tools: 'Tools',
+  features: 'Features',
+  'ide-integration': 'IDE Integration',
+  development: 'Development',
+  support: 'Support',
 };

docs/cli/_meta.ts

@@ -5,7 +5,12 @@ export default {
   commands: 'Commands',
   configuration: 'Configuration',
   'configuration-v1': 'Configuration (v1)',
+  themes: 'Themes',
   tutorials: 'Tutorials',
+  'keyboard-shortcuts': 'Keyboard Shortcuts',
+  'trusted-folders': 'Trusted Folders',
+  'qwen-ignore': 'Ignoring Files',
+  Uninstall: 'Uninstall',
 };
 
 /**

docs/cli/commands.md

@@ -145,16 +145,6 @@ Slash commands provide meta-level control over the CLI itself.
     - **`nodesc`** or **`nodescriptions`**:
       - **Description:** Hide tool descriptions, showing only the tool names.
 
-- **`/quit-confirm`**
-  - **Description:** Show a confirmation dialog before exiting Qwen Code, allowing you to choose how to handle your current session.
-  - **Usage:** `/quit-confirm`
-  - **Features:**
-    - **Quit immediately:** Exit without saving anything (equivalent to `/quit`)
-    - **Generate summary and quit:** Create a project summary using `/summary` before exiting
-    - **Save conversation and quit:** Save the current conversation with an auto-generated tag before exiting
-  - **Keyboard shortcut:** Press **Ctrl+C** twice to trigger the quit confirmation dialog
-  - **Note:** This command is automatically triggered when you press Ctrl+C once, providing a safety mechanism to prevent accidental exits.
-
 - **`/quit`** (or **`/exit`**)
   - **Description:** Exit Qwen Code immediately without any confirmation dialog.
 

docs/cli/configuration-v1.md

@@ -671,4 +671,4 @@ Note: When usage statistics are enabled, events are sent to an Alibaba Cloud RUM
   - **Category:** UI
   - **Requires Restart:** No
   - **Example:** `"enableWelcomeBack": false`
-  - **Details:** When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command and quit confirmation dialog. See the [Welcome Back documentation](./welcome-back.md) for more details.
+  - **Details:** When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command. See the [Welcome Back documentation](./welcome-back.md) for more details.

docs/developers/_meta.ts

@@ -1,23 +0,0 @@
-export default {
-  'Contribute to Qwen Code': {
-    title: 'Contribute to Qwen Code',
-    type: 'separator',
-  },
-  architecture: 'Architecture',
-  contributing: 'Contributing Guide',
-  roadmap: 'Roadmap',
-  'Qwen Code SDK': {
-    title: 'Qwen Code SDK',
-    type: 'separator',
-  },
-  'Dive Into Qwen Code': {
-    title: 'Dive Into Qwen Code',
-    type: 'separator',
-  },
-  cli: {
-    display: 'hidden',
-  },
-  core: 'Core',
-  tools: 'Tools',
-  // development: 'Development',
-};

docs/developers/roadmap.md

@@ -1 +0,0 @@
-# Qwen Code RoadMap

docs/development/_meta.ts

@@ -1,5 +1,7 @@
 export default {
+  architecture: 'Architecture',
   npm: 'NPM',
+  deployment: 'Deployment',
   telemetry: 'Telemetry',
   'integration-tests': 'Integration Tests',
   'issue-and-pr-automation': 'Issue and PR Automation',

docs/features/_meta.ts

@@ -0,0 +1,8 @@
+export default {
+  subagents: 'Subagents',
+  checkpointing: 'Checkpointing',
+  sandbox: 'Sandbox Support',
+  headless: 'Headless Mode',
+  'welcome-back': 'Welcome Back',
+  'token-caching': 'Token Caching',
+};

docs/features/welcome-back.md

@@ -81,14 +81,6 @@ The Welcome Back feature works seamlessly with the `/summary` command:
 2. **Automatic Detection:** Next time you start Qwen Code in this project, Welcome Back will detect the summary
 3. **Resume Work:** Choose to continue and the summary will be loaded as context
 
-### Quit Confirmation
-
-When exiting with `/quit-confirm` and choosing "Generate summary and quit":
-
-1. A project summary is automatically created
-2. Next session will trigger the Welcome Back dialog
-3. You can seamlessly continue your work
-
 ## File Structure
 
 The Welcome Back feature creates and uses:

docs/index.md

@@ -0,0 +1,344 @@
+# Welcome to Qwen Code documentation
+
+Qwen Code is a powerful command-line AI workflow tool adapted from [**Gemini CLI**](https://github.com/google-gemini/gemini-cli) ([details](./README.gemini.md)), specifically optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) models. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance.
+
+## 🚀 Why Choose Qwen Code?
+
+- 🎯 **Free Tier:** Up to 60 requests/min and 2,000 requests/day with your [QwenChat](https://chat.qwen.ai/) account.
+- 🧠 **Advanced Model:** Specially optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) for superior code understanding and assistance.
+- 🏆 **Comprehensive Features:** Includes subagents, Plan Mode, TodoWrite, vision model support, and full OpenAI API compatibility—all seamlessly integrated.
+- 🔧 **Built-in & Extensible Tools:** Includes file system operations, shell command execution, web fetch/search, and more—all easily extended via the Model Context Protocol (MCP) for custom integrations.
+- 💻 **Developer-Centric:** Built for terminal-first workflows—perfect for command-line enthusiasts.
+- 🛡️ **Open Source:** Apache 2.0 licensed for maximum freedom and transparency.
+
+## Installation
+
+### Prerequisites
+
+Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed.
+
+```bash
+curl -qL https://www.npmjs.com/install.sh | sh
+```
+
+### Install from npm
+
+```bash
+npm install -g @qwen-code/qwen-code@latest
+qwen --version
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/QwenLM/qwen-code.git
+cd qwen-code
+npm install
+npm install -g .
+```
+
+### Install globally with Homebrew (macOS/Linux)
+
+```bash
+brew install qwen-code
+```
+
+## Quick Start
+
+```bash
+# Start Qwen Code
+qwen
+
+# Example commands
+> Explain this codebase structure
+> Help me refactor this function
+> Generate unit tests for this module
+```
+
+### Session Management
+
+Control your token usage with configurable session limits to optimize costs and performance.
+
+#### Configure Session Token Limit
+
+Create or edit `.qwen/settings.json` in your home directory:
+
+```json
+{
+  "sessionTokenLimit": 32000
+}
+```
+
+#### Session Commands
+
+- **`/compress`** - Compress conversation history to continue within token limits
+- **`/clear`** (aliases: `/reset`, `/new`) - Clear conversation history, start a fresh session, and free up context
+- **`/stats`** - Check current token usage and limits
+
+> 📝 **Note**: Session token limit applies to a single conversation, not cumulative API calls.
+
+### Vision Model Configuration
+
+Qwen Code includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. **This feature is enabled by default** - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch.
+
+#### Skip the Switch Dialog (Optional)
+
+If you don't want to see the interactive dialog each time, configure the default behavior in your `.qwen/settings.json`:
+
+```json
+{
+  "experimental": {
+    "vlmSwitchMode": "once"
+  }
+}
+```
+
+**Available modes:**
+
+- **`"once"`** - Switch to vision model for this query only, then revert
+- **`"session"`** - Switch to vision model for the entire session
+- **`"persist"`** - Continue with current model (no switching)
+- **Not set** - Show interactive dialog each time (default)
+
+#### Command Line Override
+
+You can also set the behavior via command line:
+
+```bash
+# Switch once per query
+qwen --vlm-switch-mode once
+
+# Switch for entire session
+qwen --vlm-switch-mode session
+
+# Never switch automatically
+qwen --vlm-switch-mode persist
+```
+
+#### Disable Vision Models (Optional)
+
+To completely disable vision model support, add to your `.qwen/settings.json`:
+
+```json
+{
+  "experimental": {
+    "visionModelPreview": false
+  }
+}
+```
+
+> 💡 **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected.
+
+### Authorization
+
+Choose your preferred authentication method based on your needs:
+
+#### 1. Qwen OAuth (🚀 Recommended - Start in 30 seconds)
+
+The easiest way to get started - completely free with generous quotas:
+
+```bash
+# Just run this command and follow the browser authentication
+qwen
+```
+
+**What happens:**
+
+1. **Instant Setup**: CLI opens your browser automatically
+2. **One-Click Login**: Authenticate with your qwen.ai account
+3. **Automatic Management**: Credentials cached locally for future use
+4. **No Configuration**: Zero setup required - just start coding!
+
+**Free Tier Benefits:**
+
+- ✅ **2,000 requests/day** (no token counting needed)
+- ✅ **60 requests/minute** rate limit
+- ✅ **Automatic credential refresh**
+- ✅ **Zero cost** for individual users
+- ℹ️ **Note**: Model fallback may occur to maintain service quality
+
+#### 2. OpenAI-Compatible API
+
+Use API keys for OpenAI or other compatible providers:
+
+**Configuration Methods:**
+
+1. **Environment Variables**
+
+   ```bash
+   export OPENAI_API_KEY="your_api_key_here"
+   export OPENAI_BASE_URL="your_api_endpoint"
+   export OPENAI_MODEL="your_model_choice"
+   ```
+
+2. **Project `.env` File**
+   Create a `.env` file in your project root:
+   ```env
+   OPENAI_API_KEY=your_api_key_here
+   OPENAI_BASE_URL=your_api_endpoint
+   OPENAI_MODEL=your_model_choice
+   ```
+
+**API Provider Options**
+
+> ⚠️ **Regional Notice:**
+>
+> - **Mainland China**: Use Alibaba Cloud Bailian or ModelScope
+> - **International**: Use Alibaba Cloud ModelStudio or OpenRouter
+
+<details>
+<summary><b>🇨🇳 For Users in Mainland China</b></summary>
+
+**Option 1: Alibaba Cloud Bailian** ([Apply for API Key](https://bailian.console.aliyun.com/))
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
+export OPENAI_MODEL="qwen3-coder-plus"
+```
+
+**Option 2: ModelScope (Free Tier)** ([Apply for API Key](https://modelscope.cn/docs/model-service/API-Inference/intro))
+
+- ✅ **2,000 free API calls per day**
+- ⚠️ Connect your Aliyun account to avoid authentication errors
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
+export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"
+```
+
+</details>
+
+<details>
+<summary><b>🌍 For International Users</b></summary>
+
+**Option 1: Alibaba Cloud ModelStudio** ([Apply for API Key](https://modelstudio.console.alibabacloud.com/))
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+export OPENAI_MODEL="qwen3-coder-plus"
+```
+
+**Option 2: OpenRouter (Free Tier Available)** ([Apply for API Key](https://openrouter.ai/))
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
+export OPENAI_MODEL="qwen/qwen3-coder:free"
+```
+
+</details>
+
+## Usage Examples
+
+### 🔍 Explore Codebases
+
+```bash
+cd your-project/
+qwen
+
+# Architecture analysis
+> Describe the main pieces of this system's architecture
+> What are the key dependencies and how do they interact?
+> Find all API endpoints and their authentication methods
+```
+
+### 💻 Code Development
+
+```bash
+# Refactoring
+> Refactor this function to improve readability and performance
+> Convert this class to use dependency injection
+> Split this large module into smaller, focused components
+
+# Code generation
+> Create a REST API endpoint for user management
+> Generate unit tests for the authentication module
+> Add error handling to all database operations
+```
+
+### 🔄 Automate Workflows
+
+```bash
+# Git automation
+> Analyze git commits from the last 7 days, grouped by feature
+> Create a changelog from recent commits
+> Find all TODO comments and create GitHub issues
+
+# File operations
+> Convert all images in this directory to PNG format
+> Rename all test files to follow the *.test.ts pattern
+> Find and remove all console.log statements
+```
+
+### 🐛 Debugging & Analysis
+
+```bash
+# Performance analysis
+> Identify performance bottlenecks in this React component
+> Find all N+1 query problems in the codebase
+
+# Security audit
+> Check for potential SQL injection vulnerabilities
+> Find all hardcoded credentials or API keys
+```
+
+## Popular Tasks
+
+### 📚 Understand New Codebases
+
+```text
+> What are the core business logic components?
+> What security mechanisms are in place?
+> How does the data flow through the system?
+> What are the main design patterns used?
+> Generate a dependency graph for this module
+```
+
+### 🔨 Code Refactoring & Optimization
+
+```text
+> What parts of this module can be optimized?
+> Help me refactor this class to follow SOLID principles
+> Add proper error handling and logging
+> Convert callbacks to async/await pattern
+> Implement caching for expensive operations
+```
+
+### 📝 Documentation & Testing
+
+```text
+> Generate comprehensive JSDoc comments for all public APIs
+> Write unit tests with edge cases for this component
+> Create API documentation in OpenAPI format
+> Add inline comments explaining complex algorithms
+> Generate a README for this module
+```
+
+### 🚀 Development Acceleration
+
+```text
+> Set up a new Express server with authentication
+> Create a React component with TypeScript and tests
+> Implement a rate limiter middleware
+> Add database migrations for new schema
+> Configure CI/CD pipeline for this project
+```
+
+## Commands & Shortcuts
+
+### Session Commands
+
+- `/help` - Display available commands
+- `/clear` (aliases: `/reset`, `/new`) - Clear conversation history and start a fresh session
+- `/compress` - Compress history to save tokens
+- `/stats` - Show current session information
+- `/exit` or `/quit` - Exit Qwen Code
+
+### Keyboard Shortcuts
+
+- `Ctrl+C` - Cancel current operation
+- `Ctrl+D` - Exit (on empty line)
+- `Up/Down` - Navigate command history

docs/sidebar.json

@@ -0,0 +1,68 @@
+[
+  {
+    "label": "Overview",
+    "items": [
+      { "label": "Welcome", "slug": "docs" },
+      { "label": "Execution and Deployment", "slug": "docs/deployment" },
+      { "label": "Architecture Overview", "slug": "docs/architecture" }
+    ]
+  },
+  {
+    "label": "CLI",
+    "items": [
+      { "label": "Introduction", "slug": "docs/cli" },
+      { "label": "Authentication", "slug": "docs/cli/authentication" },
+      { "label": "Commands", "slug": "docs/cli/commands" },
+      { "label": "Configuration", "slug": "docs/cli/configuration" },
+      { "label": "Checkpointing", "slug": "docs/checkpointing" },
+      { "label": "Extensions", "slug": "docs/extension" },
+      { "label": "Headless Mode", "slug": "docs/headless" },
+      { "label": "IDE Integration", "slug": "docs/ide-integration" },
+      {
+        "label": "IDE Companion Spec",
+        "slug": "docs/ide-companion-spec"
+      },
+      { "label": "Telemetry", "slug": "docs/telemetry" },
+      { "label": "Themes", "slug": "docs/cli/themes" },
+      { "label": "Token Caching", "slug": "docs/cli/token-caching" },
+      { "label": "Trusted Folders", "slug": "docs/trusted-folders" },
+      { "label": "Tutorials", "slug": "docs/cli/tutorials" }
+    ]
+  },
+  {
+    "label": "Core",
+    "items": [
+      { "label": "Introduction", "slug": "docs/core" },
+      { "label": "Tools API", "slug": "docs/core/tools-api" },
+      { "label": "Memory Import Processor", "slug": "docs/core/memport" }
+    ]
+  },
+  {
+    "label": "Tools",
+    "items": [
+      { "label": "Overview", "slug": "docs/tools" },
+      { "label": "File System", "slug": "docs/tools/file-system" },
+      { "label": "Multi-File Read", "slug": "docs/tools/multi-file" },
+      { "label": "Shell", "slug": "docs/tools/shell" },
+      { "label": "Web Fetch", "slug": "docs/tools/web-fetch" },
+      { "label": "Web Search", "slug": "docs/tools/web-search" },
+      { "label": "Memory", "slug": "docs/tools/memory" },
+      { "label": "MCP Servers", "slug": "docs/tools/mcp-server" },
+      { "label": "Sandboxing", "slug": "docs/sandbox" }
+    ]
+  },
+  {
+    "label": "Development",
+    "items": [
+      { "label": "NPM", "slug": "docs/npm" },
+      { "label": "Releases", "slug": "docs/releases" }
+    ]
+  },
+  {
+    "label": "Support",
+    "items": [
+      { "label": "Troubleshooting", "slug": "docs/troubleshooting" },
+      { "label": "Terms of Service", "slug": "docs/tos-privacy" }
+    ]
+  }
+]

docs/support/_meta.ts

@@ -1,6 +1,4 @@
 export default {
   troubleshooting: 'Troubleshooting',
   'tos-privacy': 'Terms of Service',
-
-  Uninstall: 'Uninstall',
 };

docs/users/_meta.ts

@@ -1,28 +0,0 @@
-export default {
-  'Getting started': {
-    type: 'separator',
-    title: 'Getting started', // Title is optional
-  },
-  overview: 'Overview',
-  'quick-start': 'QuickStart',
-  'common-workflow': 'Command Workflows',
-  'Outside of the terminal': {
-    type: 'separator',
-    title: 'Outside of the terminal', // Title is optional
-  },
-  'integration-github-action': 'Github Action',
-  'integration-vscode': 'VSCode Extension',
-  'integration-zed': 'Zed IDE',
-  'Code with Qwen Code': {
-    type: 'separator',
-    title: 'Code with Qwen Code', // Title is optional
-  },
-  features: 'Features',
-  configuration: 'Configuration',
-  reference: 'Reference',
-  support: 'Support',
-  // need refine
-  'ide-integration': {
-    display: 'hidden',
-  },
-};

docs/users/configuration/_meta.ts

@@ -1,7 +0,0 @@
-export default {
-  settings: 'Settings File',
-  memory: 'Memory Management',
-  'trusted-folders': 'Trusted Folders',
-  'qwen-ignore': 'Ignoring Files',
-  themes: 'Themes',
-};

docs/users/features/_meta.ts

@@ -1,15 +0,0 @@
-export default {
-  subagents: 'Subagents',
-  'sub-commands': 'Sub Commands',
-  checkpointing: {
-    display: 'hidden',
-  },
-  headless: 'Headless Mode',
-  'welcome-back': {
-    display: 'hidden',
-  },
-  'approval-mode': 'Approval Mode',
-  'token-caching': 'Token Caching',
-  mcp: 'MCP',
-  sandbox: 'Sandboxing',
-};

docs/users/reference/_meta.ts

@@ -1,3 +0,0 @@
-export default {
-  'keyboard-shortcuts': 'Keyboard Shortcuts',
-};

eslint.config.js

@@ -22,6 +22,7 @@ export default tseslint.config(
       'bundle/**',
       'package/bundle/**',
       '.integration-tests/**',
+      'packages/**/.integration-test/**',
       'dist/**',
     ],
   },
@@ -150,7 +151,7 @@ export default tseslint.config(
     },
   },
   {
-    files: ['packages/*/src/**/*.test.{ts,tsx}'],
+    files: ['packages/*/src/**/*.test.{ts,tsx}', 'packages/**/test/**/*.test.{ts,tsx}'],
     plugins: {
       vitest,
     },
@@ -158,11 +159,19 @@ export default tseslint.config(
       ...vitest.configs.recommended.rules,
       'vitest/expect-expect': 'off',
       'vitest/no-commented-out-tests': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
     },
   },
   // extra settings for scripts that we run directly with node
   {
-    files: ['./scripts/**/*.js', 'esbuild.config.js'],
+    files: ['./scripts/**/*.js', 'esbuild.config.js', 'packages/*/scripts/**/*.js'],
     languageOptions: {
       globals: {
         ...globals.node,
@@ -229,7 +238,7 @@ export default tseslint.config(
   prettierConfig,
   // extra settings for scripts that we run directly with node
   {
-    files: ['./integration-tests/**/*.js'],
+    files: ['./integration-tests/**/*.{js,ts,tsx}'],
     languageOptions: {
       globals: {
         ...globals.node,

integration-tests/globalSetup.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2025 Qwen Team
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -30,6 +30,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const rootDir = join(__dirname, '..');
 const integrationTestsDir = join(rootDir, '.integration-tests');
 let runDir = ''; // Make runDir accessible in teardown
+let sdkE2eRunDir = ''; // SDK E2E test run directory
 
 const memoryFilePath = join(
   os.homedir(),
@@ -48,14 +49,36 @@ export async function setup() {
     // File doesn't exist, which is fine.
   }
 
+  // Setup for CLI integration tests
   runDir = join(integrationTestsDir, `${Date.now()}`);
   await mkdir(runDir, { recursive: true });
 
+  // Setup for SDK E2E tests (separate directory with prefix)
+  sdkE2eRunDir = join(integrationTestsDir, `sdk-e2e-${Date.now()}`);
+  await mkdir(sdkE2eRunDir, { recursive: true });
+
   // Clean up old test runs, but keep the latest few for debugging
   try {
     const testRuns = await readdir(integrationTestsDir);
-    if (testRuns.length > 5) {
-      const oldRuns = testRuns.sort().slice(0, testRuns.length - 5);
+
+    // Clean up old CLI integration test runs (without sdk-e2e- prefix)
+    const cliTestRuns = testRuns.filter((run) => !run.startsWith('sdk-e2e-'));
+    if (cliTestRuns.length > 5) {
+      const oldRuns = cliTestRuns.sort().slice(0, cliTestRuns.length - 5);
+      await Promise.all(
+        oldRuns.map((oldRun) =>
+          rm(join(integrationTestsDir, oldRun), {
+            recursive: true,
+            force: true,
+          }),
+        ),
+      );
+    }
+
+    // Clean up old SDK E2E test runs (with sdk-e2e- prefix)
+    const sdkTestRuns = testRuns.filter((run) => run.startsWith('sdk-e2e-'));
+    if (sdkTestRuns.length > 5) {
+      const oldRuns = sdkTestRuns.sort().slice(0, sdkTestRuns.length - 5);
       await Promise.all(
         oldRuns.map((oldRun) =>
           rm(join(integrationTestsDir, oldRun), {
@@ -69,24 +92,37 @@ export async function setup() {
     console.error('Error cleaning up old test runs:', e);
   }
 
+  // Environment variables for CLI integration tests
   process.env['INTEGRATION_TEST_FILE_DIR'] = runDir;
   process.env['GEMINI_CLI_INTEGRATION_TEST'] = 'true';
   process.env['TELEMETRY_LOG_FILE'] = join(runDir, 'telemetry.log');
 
+  // Environment variables for SDK E2E tests
+  process.env['E2E_TEST_FILE_DIR'] = sdkE2eRunDir;
+  process.env['TEST_CLI_PATH'] = join(rootDir, 'dist/cli.js');
+
   if (process.env['KEEP_OUTPUT']) {
     console.log(`Keeping output for test run in: ${runDir}`);
+    console.log(`Keeping output for SDK E2E test run in: ${sdkE2eRunDir}`);
   }
   process.env['VERBOSE'] = process.env['VERBOSE'] ?? 'false';
 
   console.log(`\nIntegration test output directory: ${runDir}`);
+  console.log(`SDK E2E test output directory: ${sdkE2eRunDir}`);
+  console.log(`CLI path: ${process.env['TEST_CLI_PATH']}`);
 }
 
 export async function teardown() {
-  // Cleanup the test run directory unless KEEP_OUTPUT is set
+  // Cleanup the CLI test run directory unless KEEP_OUTPUT is set
   if (process.env['KEEP_OUTPUT'] !== 'true' && runDir) {
     await rm(runDir, { recursive: true, force: true });
   }
 
+  // Cleanup the SDK E2E test run directory unless KEEP_OUTPUT is set
+  if (process.env['KEEP_OUTPUT'] !== 'true' && sdkE2eRunDir) {
+    await rm(sdkE2eRunDir, { recursive: true, force: true });
+  }
+
   if (originalMemoryContent !== null) {
     await mkdir(dirname(memoryFilePath), { recursive: true });
     await writeFile(memoryFilePath, originalMemoryContent, 'utf-8');

integration-tests/sdk-typescript/abort-and-lifecycle.test.ts

@@ -0,0 +1,486 @@
+/**
+ * E2E tests based on abort-and-lifecycle.ts example
+ * Tests AbortController integration and process lifecycle management
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  AbortError,
+  isAbortError,
+  isSDKAssistantMessage,
+  type TextBlock,
+  type ContentBlock,
+} from '@qwen-code/sdk';
+import { SDKTestHelper, createSharedTestOptions } from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+describe('AbortController and Process Lifecycle (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('abort-and-lifecycle');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+  describe('Basic AbortController Usage', () => {
+    it('should support AbortController cancellation', async () => {
+      const controller = new AbortController();
+
+      // Abort after 5 seconds
+      setTimeout(() => {
+        controller.abort();
+      }, 5000);
+
+      const q = query({
+        prompt: 'Write a very long story about TypeScript programming',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 100);
+
+            // Should receive some content before abort
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+
+        // Should not reach here - query should be aborted
+        expect(false).toBe(true);
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle abort during query execution', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      let receivedFirstMessage = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            if (!receivedFirstMessage) {
+              // Abort immediately after receiving first assistant message
+              receivedFirstMessage = true;
+              controller.abort();
+            }
+          }
+        }
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+        expect(error instanceof AbortError).toBe(true);
+        // Should have received at least one message before abort
+        expect(receivedFirstMessage).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle abort immediately after query starts', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Write a very long essay',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Abort immediately after query initialization
+      setTimeout(() => {
+        controller.abort();
+      }, 200);
+
+      try {
+        for await (const _message of q) {
+          // May or may not receive messages before abort
+        }
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+        expect(error instanceof AbortError).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Process Lifecycle Monitoring', () => {
+    it('should handle normal process completion', async () => {
+      const q = query({
+        prompt: 'Why do we choose to go to the moon?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let completedSuccessfully = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 100);
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+
+        completedSuccessfully = true;
+      } catch (error) {
+        // Should not throw for normal completion
+        expect(false).toBe(true);
+      } finally {
+        await q.close();
+        expect(completedSuccessfully).toBe(true);
+      }
+    });
+
+    it('should handle process cleanup after error', async () => {
+      const q = query({
+        prompt: 'Hello world',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 50);
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+      } catch (error) {
+        // Expected to potentially have errors
+      } finally {
+        // Should cleanup successfully even after error
+        await q.close();
+        expect(true).toBe(true); // Cleanup completed
+      }
+    });
+  });
+
+  describe('Input Stream Control', () => {
+    it('should support endInput() method', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let receivedResponse = false;
+      let endInputCalled = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message) && !endInputCalled) {
+            const textBlocks = message.message.content.filter(
+              (block: ContentBlock): block is TextBlock =>
+                block.type === 'text',
+            );
+            const text = textBlocks.map((b: TextBlock) => b.text).join('');
+
+            expect(text.length).toBeGreaterThan(0);
+            receivedResponse = true;
+
+            // End input after receiving first response
+            q.endInput();
+            endInputCalled = true;
+          }
+        }
+
+        expect(receivedResponse).toBe(true);
+        expect(endInputCalled).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling and Recovery', () => {
+    it('should handle invalid executable path', async () => {
+      try {
+        const q = query({
+          prompt: 'Hello world',
+          options: {
+            pathToQwenExecutable: '/nonexistent/path/to/cli',
+            debug: false,
+          },
+        });
+
+        // Should not reach here - query() should throw immediately
+        for await (const _message of q) {
+          // Should not reach here
+        }
+
+        // Should not reach here
+        expect(false).toBe(true);
+      } catch (error) {
+        expect(error instanceof Error).toBe(true);
+        expect((error as Error).message).toBeDefined();
+        expect((error as Error).message).toContain(
+          'Invalid pathToQwenExecutable',
+        );
+      }
+    });
+
+    it('should throw AbortError with correct properties', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Explain the concept of async programming',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Abort after allowing query to start
+      setTimeout(() => controller.abort(), 1000);
+
+      try {
+        for await (const _message of q) {
+          // May receive some messages before abort
+        }
+      } catch (error) {
+        // Verify error type and helper functions
+        expect(isAbortError(error)).toBe(true);
+        expect(error instanceof AbortError).toBe(true);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBeDefined();
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Debugging with stderr callback', () => {
+    it('should capture stderr messages when debug is enabled', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Why do we choose to go to the moon?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 50);
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+      } finally {
+        await q.close();
+        expect(stderrMessages.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should not capture stderr when debug is disabled', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const _message of q) {
+          // Consume all messages
+        }
+      } finally {
+        await q.close();
+        // Should have minimal or no stderr output when debug is false
+        expect(stderrMessages.length).toBeLessThan(10);
+      }
+    });
+  });
+
+  describe('Abort with Cleanup', () => {
+    it('should cleanup properly after abort', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Write a very long essay about programming',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Abort immediately
+      setTimeout(() => controller.abort(), 100);
+
+      try {
+        for await (const _message of q) {
+          // May receive some messages before abort
+        }
+      } catch (error) {
+        if (error instanceof AbortError) {
+          expect(true).toBe(true); // Expected abort error
+        } else {
+          throw error; // Unexpected error
+        }
+      } finally {
+        await q.close();
+        expect(true).toBe(true); // Cleanup completed after abort
+      }
+    });
+
+    it('should handle multiple abort calls gracefully', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Count to 100',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Multiple abort calls
+      setTimeout(() => controller.abort(), 100);
+      setTimeout(() => controller.abort(), 200);
+      setTimeout(() => controller.abort(), 300);
+
+      try {
+        for await (const _message of q) {
+          // Should be interrupted
+        }
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Resource Management Edge Cases', () => {
+    it('should handle close() called multiple times', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      // Start the query
+      const iterator = q[Symbol.asyncIterator]();
+      await iterator.next();
+
+      // Close multiple times
+      await q.close();
+      await q.close();
+      await q.close();
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+
+    it('should handle abort after close', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Start and close immediately
+      const iterator = q[Symbol.asyncIterator]();
+      await iterator.next();
+      await q.close();
+
+      // Abort after close
+      controller.abort();
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+  });
+});

integration-tests/sdk-typescript/configuration-options.test.ts

@@ -0,0 +1,640 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * E2E tests for SDK configuration options:
+ * - logLevel: Controls SDK internal logging verbosity
+ * - env: Environment variables passed to CLI process
+ * - authType: Authentication type for AI service
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  type SDKMessage,
+} from '@qwen-code/sdk';
+import {
+  SDKTestHelper,
+  extractText,
+  createSharedTestOptions,
+  assertSuccessfulCompletion,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+describe('Configuration Options (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('configuration-options');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+
+  describe('logLevel Option', () => {
+    it('should respect logLevel: debug and capture detailed logs', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 1 + 1? Just answer the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'debug',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Debug level should produce verbose logging
+        expect(stderrMessages.length).toBeGreaterThan(0);
+
+        // Debug logs should contain detailed information like [DEBUG]
+        const hasDebugLogs = stderrMessages.some(
+          (msg) => msg.includes('[DEBUG]') || msg.includes('debug'),
+        );
+        expect(hasDebugLogs).toBe(true);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect logLevel: info and filter out debug messages', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 2 + 2? Just answer the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'info',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Info level should filter out debug messages
+        // Check that we don't have [DEBUG] level messages from the SDK logger
+        const sdkDebugLogs = stderrMessages.filter(
+          (msg) =>
+            msg.includes('[DEBUG]') && msg.includes('[ProcessTransport]'),
+        );
+        expect(sdkDebugLogs.length).toBe(0);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect logLevel: warn and only show warnings and errors', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'warn',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Warn level should filter out info and debug messages from SDK
+        const sdkInfoOrDebugLogs = stderrMessages.filter(
+          (msg) =>
+            (msg.includes('[DEBUG]') || msg.includes('[INFO]')) &&
+            (msg.includes('[ProcessTransport]') ||
+              msg.includes('[createQuery]') ||
+              msg.includes('[Query]')),
+        );
+        expect(sdkInfoOrDebugLogs.length).toBe(0);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect logLevel: error and only show error messages', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello world',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'error',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Error level should filter out all non-error messages from SDK
+        const sdkNonErrorLogs = stderrMessages.filter(
+          (msg) =>
+            (msg.includes('[DEBUG]') ||
+              msg.includes('[INFO]') ||
+              msg.includes('[WARN]')) &&
+            (msg.includes('[ProcessTransport]') ||
+              msg.includes('[createQuery]') ||
+              msg.includes('[Query]')),
+        );
+        expect(sdkNonErrorLogs.length).toBe(0);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should use logLevel over debug flag when both are provided', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 3 + 3?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: true, // Would normally enable debug logging
+          logLevel: 'error', // But logLevel should take precedence
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const _message of q) {
+          // Consume all messages
+        }
+
+        // logLevel: error should suppress debug/info/warn even with debug: true
+        const sdkNonErrorLogs = stderrMessages.filter(
+          (msg) =>
+            (msg.includes('[DEBUG]') ||
+              msg.includes('[INFO]') ||
+              msg.includes('[WARN]')) &&
+            (msg.includes('[ProcessTransport]') ||
+              msg.includes('[createQuery]') ||
+              msg.includes('[Query]')),
+        );
+        expect(sdkNonErrorLogs.length).toBe(0);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('env Option', () => {
+    it('should pass custom environment variables to CLI process', async () => {
+      const q = query({
+        prompt: 'What is 1 + 1? Just the number please.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            CUSTOM_TEST_VAR: 'test_value_12345',
+            ANOTHER_VAR: 'another_value',
+          },
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // The query should complete successfully with custom env vars
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should allow overriding existing environment variables', async () => {
+      // Store original value for comparison
+      const originalPath = process.env['PATH'];
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            // Override an existing env var (not PATH as it might break things)
+            MY_TEST_OVERRIDE: 'overridden_value',
+          },
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Query should complete successfully
+        assertSuccessfulCompletion(messages);
+
+        // Verify original process env is not modified
+        expect(process.env['PATH']).toBe(originalPath);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should work with empty env object', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {},
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should support setting model-related environment variables', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            // Common model-related env vars that CLI might respect
+            OPENAI_API_KEY: process.env['OPENAI_API_KEY'] || 'test-key',
+          },
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should complete (may succeed or fail based on API key validity)
+        expect(messages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should not leak env vars between query instances', async () => {
+      // First query with specific env var
+      const q1 = query({
+        prompt: 'Say one',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            ISOLATED_VAR_1: 'value_1',
+          },
+          debug: false,
+        },
+      });
+
+      try {
+        for await (const _message of q1) {
+          // Consume messages
+        }
+      } finally {
+        await q1.close();
+      }
+
+      // Second query with different env var
+      const q2 = query({
+        prompt: 'Say two',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            ISOLATED_VAR_2: 'value_2',
+          },
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q2) {
+          messages.push(message);
+        }
+
+        // Second query should complete successfully
+        assertSuccessfulCompletion(messages);
+
+        // Verify process.env is not polluted by either query
+        expect(process.env['ISOLATED_VAR_1']).toBeUndefined();
+        expect(process.env['ISOLATED_VAR_2']).toBeUndefined();
+      } finally {
+        await q2.close();
+      }
+    });
+  });
+
+  describe('authType Option', () => {
+    it('should accept authType: openai', async () => {
+      const q = query({
+        prompt: 'What is 1 + 1? Just the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          authType: 'openai',
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Query should complete with openai auth type
+        assertSuccessfulCompletion(messages);
+
+        // Verify we got an assistant response
+        const assistantMessages = messages.filter(isSDKAssistantMessage);
+        expect(assistantMessages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+
+    // Skip in containerized sandbox environments - qwen-oauth requires user interaction
+    // which is not possible in Docker/Podman CI environments
+    it.skipIf(
+      process.env['SANDBOX'] === 'sandbox:docker' ||
+        process.env['SANDBOX'] === 'sandbox:podman',
+    )('should accept authType: qwen-oauth', async () => {
+      // Note: qwen-oauth requires credentials in ~/.qwen and user interaction
+      // Without credentials, the auth process will timeout waiting for user
+      // This test verifies the option is accepted and passed correctly to CLI
+
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          authType: 'qwen-oauth',
+          debug: true,
+          logLevel: 'debug',
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        // Use a timeout to avoid hanging when credentials are not configured
+        const timeoutPromise = new Promise<'timeout'>((resolve) =>
+          setTimeout(() => resolve('timeout'), 20000),
+        );
+
+        const collectMessages = async () => {
+          for await (const message of q) {
+            messages.push(message);
+          }
+          return 'completed';
+        };
+
+        const result = await Promise.race([collectMessages(), timeoutPromise]);
+
+        if (result === 'timeout') {
+          // Timeout is expected when OAuth credentials are not configured
+          // Verify that CLI was spawned with correct --auth-type argument
+          const hasAuthTypeArg = stderrMessages.some((msg) =>
+            msg.includes('--auth-type'),
+          );
+          expect(hasAuthTypeArg).toBe(true);
+        } else {
+          // If credentials exist and auth completed, verify we got messages
+          expect(messages.length).toBeGreaterThan(0);
+        }
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should use default auth when authType is not specified', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2? Just the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          // authType not specified - should use default
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Query should complete with default auth
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should properly pass authType to CLI process', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Say hi',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          authType: 'openai',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // There should be spawn log containing auth-type
+        const hasAuthTypeArg = stderrMessages.some((msg) =>
+          msg.includes('--auth-type'),
+        );
+        expect(hasAuthTypeArg).toBe(true);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Combined Options', () => {
+    it('should work with logLevel, env, and authType together', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 3 + 3? Just the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'debug',
+          env: {
+            COMBINED_TEST_VAR: 'combined_value',
+          },
+          authType: 'openai',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // All three options should work together
+        expect(stderrMessages.length).toBeGreaterThan(0); // logLevel: debug produces logs
+        expect(assistantText).toMatch(/6/); // Query should work
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should maintain system message consistency with all options', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'info',
+          env: {
+            SYSTEM_MSG_TEST: 'test',
+          },
+          authType: 'openai',
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should have system init message
+        const systemMessages = messages.filter(isSDKSystemMessage);
+        const initMessage = systemMessages.find((m) => m.subtype === 'init');
+
+        expect(initMessage).toBeDefined();
+        expect(initMessage!.session_id).toBeDefined();
+        expect(initMessage!.tools).toBeDefined();
+        expect(initMessage!.permission_mode).toBeDefined();
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});

integration-tests/sdk-typescript/mcp-server.test.ts

@@ -0,0 +1,405 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * E2E tests for MCP (Model Context Protocol) server integration via SDK
+ * Tests that the SDK can properly interact with MCP servers configured in qwen-code
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  isSDKResultMessage,
+  isSDKSystemMessage,
+  isSDKUserMessage,
+  type SDKMessage,
+  type ToolUseBlock,
+  type SDKSystemMessage,
+} from '@qwen-code/sdk';
+import {
+  SDKTestHelper,
+  createMCPServer,
+  extractText,
+  findToolUseBlocks,
+  createSharedTestOptions,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = {
+  ...createSharedTestOptions(),
+  permissionMode: 'yolo' as const,
+};
+
+describe('MCP Server Integration (E2E)', () => {
+  let helper: SDKTestHelper;
+  let serverScriptPath: string;
+  let testDir: string;
+
+  beforeEach(async () => {
+    // Create isolated test environment using SDKTestHelper
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('mcp-server-integration');
+
+    // Create MCP server using the helper utility
+    const mcpServer = await createMCPServer(helper, 'math', 'test-math-server');
+    serverScriptPath = mcpServer.scriptPath;
+  });
+
+  afterEach(async () => {
+    // Cleanup test directory
+    await helper.cleanup();
+  });
+
+  describe('Basic MCP Tool Usage', () => {
+    it('should use MCP add tool to add two numbers', async () => {
+      const q = query({
+        prompt:
+          'Use the add tool to calculate 5 + 10. Just give me the result.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      let foundToolUse = false;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message, 'add');
+            if (toolUseBlocks.length > 0) {
+              foundToolUse = true;
+            }
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate tool was called
+        expect(foundToolUse).toBe(true);
+
+        // Validate result contains expected answer
+        expect(assistantText).toMatch(/15/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+        if (isSDKResultMessage(lastMessage)) {
+          expect(lastMessage.subtype).toBe('success');
+        }
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should use MCP multiply tool to multiply two numbers', async () => {
+      const q = query({
+        prompt:
+          'Use the multiply tool to calculate 6 * 7. Just give me the result.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      let foundToolUse = false;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message, 'multiply');
+            if (toolUseBlocks.length > 0) {
+              foundToolUse = true;
+            }
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate tool was called
+        expect(foundToolUse).toBe(true);
+
+        // Validate result contains expected answer
+        expect(assistantText).toMatch(/42/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('MCP Server Discovery', () => {
+    it('should list MCP servers in system init message', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      let systemMessage: SDKSystemMessage | null = null;
+
+      try {
+        for await (const message of q) {
+          if (isSDKSystemMessage(message) && message.subtype === 'init') {
+            systemMessage = message;
+            break;
+          }
+        }
+
+        // Validate MCP server is listed
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.mcp_servers).toBeDefined();
+        expect(Array.isArray(systemMessage!.mcp_servers)).toBe(true);
+
+        // Find our test server
+        const testServer = systemMessage!.mcp_servers?.find(
+          (server) => server.name === 'test-math-server',
+        );
+        expect(testServer).toBeDefined();
+
+        // Note: tools are not exposed in the mcp_servers array in system message
+        // They are available through the MCP protocol but not in the init message
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Complex MCP Operations', () => {
+    it('should chain multiple MCP tool calls', async () => {
+      const q = query({
+        prompt:
+          'First use add to calculate 10 + 5, then multiply the result by 2. Give me the final answer.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      const toolCalls: string[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message);
+            toolUseBlocks.forEach((block) => {
+              toolCalls.push(block.name);
+            });
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate both tools were called
+        expect(toolCalls).toContain('add');
+        expect(toolCalls).toContain('multiply');
+
+        // Validate result: (10 + 5) * 2 = 30
+        expect(assistantText).toMatch(/30/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle multiple calls to the same MCP tool', async () => {
+      const q = query({
+        prompt:
+          'Use the add tool twice: first add 1 + 2, then add 3 + 4. Tell me both results.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      const addToolCalls: ToolUseBlock[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message, 'add');
+            addToolCalls.push(...toolUseBlocks);
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate add tool was called at least twice
+        expect(addToolCalls.length).toBeGreaterThanOrEqual(2);
+
+        // Validate results contain expected answers: 3 and 7
+        expect(assistantText).toMatch(/3/);
+        expect(assistantText).toMatch(/7/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('MCP Tool Message Flow', () => {
+    it('should receive proper message sequence for MCP tool usage', async () => {
+      const q = query({
+        prompt: 'Use add to calculate 2 + 3',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messageTypes: string[] = [];
+      let foundToolUse = false;
+      let foundToolResult = false;
+
+      try {
+        for await (const message of q) {
+          messageTypes.push(message.type);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message);
+            if (toolUseBlocks.length > 0) {
+              foundToolUse = true;
+              expect(toolUseBlocks[0].name).toBe('add');
+              expect(toolUseBlocks[0].input).toBeDefined();
+            }
+          }
+
+          if (isSDKUserMessage(message)) {
+            const content = message.message.content;
+            const contentArray = Array.isArray(content)
+              ? content
+              : [{ type: 'text', text: content }];
+            const toolResultBlock = contentArray.find(
+              (block) => block.type === 'tool_result',
+            );
+            if (toolResultBlock) {
+              foundToolResult = true;
+            }
+          }
+        }
+
+        // Validate message flow
+        expect(foundToolUse).toBe(true);
+        expect(foundToolResult).toBe(true);
+        expect(messageTypes).toContain('system');
+        expect(messageTypes).toContain('assistant');
+        expect(messageTypes).toContain('user');
+        expect(messageTypes).toContain('result');
+
+        // Result should be last message
+        expect(messageTypes[messageTypes.length - 1]).toBe('result');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle gracefully when MCP tool is not available', async () => {
+      const q = query({
+        prompt: 'Use the subtract tool to calculate 10 - 5',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Should complete without crashing
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+
+        // Assistant should indicate tool is not available or provide alternative
+        expect(assistantText.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});

integration-tests/sdk-typescript/multi-turn.test.ts

@@ -0,0 +1,559 @@
+/**
+ * E2E tests based on multi-turn.ts example
+ * Tests multi-turn conversation functionality with real CLI
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKUserMessage,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+  isSDKPartialAssistantMessage,
+  isControlRequest,
+  isControlResponse,
+  isControlCancel,
+  type SDKUserMessage,
+  type SDKAssistantMessage,
+  type TextBlock,
+  type ContentBlock,
+  type SDKMessage,
+  type ControlMessage,
+  type ToolUseBlock,
+} from '@qwen-code/sdk';
+import { SDKTestHelper, createSharedTestOptions } from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+/**
+ * Determine the message type using protocol type guards
+ */
+function getMessageType(message: SDKMessage | ControlMessage): string {
+  if (isSDKUserMessage(message)) {
+    return '🧑 USER';
+  } else if (isSDKAssistantMessage(message)) {
+    return '🤖 ASSISTANT';
+  } else if (isSDKSystemMessage(message)) {
+    return `🖥️ SYSTEM(${message.subtype})`;
+  } else if (isSDKResultMessage(message)) {
+    return `✅ RESULT(${message.subtype})`;
+  } else if (isSDKPartialAssistantMessage(message)) {
+    return '⏳ STREAM_EVENT';
+  } else if (isControlRequest(message)) {
+    return `🎮 CONTROL_REQUEST(${message.request.subtype})`;
+  } else if (isControlResponse(message)) {
+    return `📭 CONTROL_RESPONSE(${message.response.subtype})`;
+  } else if (isControlCancel(message)) {
+    return '🛑 CONTROL_CANCEL';
+  } else {
+    return '❓ UNKNOWN';
+  }
+}
+
+/**
+ * Helper to extract text from ContentBlock array
+ */
+function extractText(content: ContentBlock[]): string {
+  return content
+    .filter((block): block is TextBlock => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+}
+
+describe('Multi-Turn Conversations (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('multi-turn');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+
+  describe('AsyncIterable Prompt Support', () => {
+    it('should handle multi-turn conversation using AsyncIterable prompt', async () => {
+      // Create multi-turn conversation generator
+      async function* createMultiTurnConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 1 + 1?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 2 + 2?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 3 + 3?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      // Create multi-turn query using AsyncIterable prompt
+      const q = query({
+        prompt: createMultiTurnConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      const assistantMessages: SDKAssistantMessage[] = [];
+      const assistantTexts: string[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+            const text = extractText(message.message.content);
+            assistantTexts.push(text);
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(3);
+
+        // Validate content of responses
+        expect(assistantTexts[0]).toMatch(/2/);
+        expect(assistantTexts[1]).toMatch(/4/);
+        expect(assistantTexts[2]).toMatch(/6/);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should maintain session context across turns', async () => {
+      async function* createContextualConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content:
+              'Suppose we have 3 rabbits and 4 carrots. How many animals are there?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'How many animals are there? Only output the number',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createContextualConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const assistantMessages: SDKAssistantMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+          }
+        }
+
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(2);
+
+        // The second response should reference the color blue
+        const secondResponse = extractText(
+          assistantMessages[1].message.content,
+        );
+        expect(secondResponse.toLowerCase()).toContain('3');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Tool Usage in Multi-Turn', () => {
+    it('should handle tool usage across multiple turns', async () => {
+      async function* createToolConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Create a file named test.txt with content "hello"',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Now read the test.txt file',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createToolConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          permissionMode: 'yolo',
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let toolUseCount = 0;
+      const assistantMessages: SDKAssistantMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+            const hasToolUseBlock = message.message.content.some(
+              (block: ContentBlock): block is ToolUseBlock =>
+                block.type === 'tool_use',
+            );
+            if (hasToolUseBlock) {
+              toolUseCount++;
+            }
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(toolUseCount).toBeGreaterThan(0);
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(2);
+
+        // Validate second response mentions the file content
+        const secondResponse = extractText(
+          assistantMessages[assistantMessages.length - 1].message.content,
+        );
+        expect(secondResponse.toLowerCase()).toMatch(/hello|test\.txt/);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Message Flow and Sequencing', () => {
+    it('should process messages in correct sequence', async () => {
+      async function* createSequentialConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'First question: What is 1 + 1?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Second question: What is 2 + 2?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createSequentialConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messageSequence: string[] = [];
+      const assistantResponses: string[] = [];
+
+      try {
+        for await (const message of q) {
+          const messageType = getMessageType(message);
+          messageSequence.push(messageType);
+
+          if (isSDKAssistantMessage(message)) {
+            const text = extractText(message.message.content);
+            assistantResponses.push(text);
+          }
+        }
+
+        expect(messageSequence.length).toBeGreaterThan(0);
+        expect(assistantResponses.length).toBeGreaterThanOrEqual(2);
+
+        // Should end with result
+        expect(messageSequence[messageSequence.length - 1]).toContain('RESULT');
+
+        // Should have assistant responses
+        expect(messageSequence.some((type) => type.includes('ASSISTANT'))).toBe(
+          true,
+        );
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle conversation completion correctly', async () => {
+      async function* createSimpleConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Hello',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Goodbye',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createSimpleConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let completedNaturally = false;
+      let messageCount = 0;
+
+      try {
+        for await (const message of q) {
+          messageCount++;
+
+          if (isSDKResultMessage(message)) {
+            completedNaturally = true;
+            expect(message.subtype).toBe('success');
+          }
+        }
+
+        expect(messageCount).toBeGreaterThan(0);
+        expect(completedNaturally).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling in Multi-Turn', () => {
+    it('should handle empty conversation gracefully', async () => {
+      async function* createEmptyConversation(): AsyncIterable<SDKUserMessage> {
+        // Generator that yields nothing
+        /* eslint-disable no-constant-condition */
+        if (false) {
+          yield {} as SDKUserMessage; // Unreachable, but satisfies TypeScript
+        }
+      }
+
+      const q = query({
+        prompt: createEmptyConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should handle empty conversation without crashing
+        expect(true).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle conversation with delays', async () => {
+      async function* createDelayedConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'First message',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        // Longer delay to test patience
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Second message after delay',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createDelayedConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const assistantMessages: SDKAssistantMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+          }
+        }
+
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(2);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Partial Messages in Multi-Turn', () => {
+    it('should receive partial messages when includePartialMessages is enabled', async () => {
+      async function* createMultiTurnConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 1 + 1?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 2 + 2?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createMultiTurnConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          includePartialMessages: true,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let partialMessageCount = 0;
+      let assistantMessageCount = 0;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKPartialAssistantMessage(message)) {
+            partialMessageCount++;
+          }
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessageCount++;
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(partialMessageCount).toBeGreaterThan(0);
+        expect(assistantMessageCount).toBeGreaterThanOrEqual(2);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});