@qwen-code/sdk 0.1.0-preview.0

package/dist/index.d.ts

@@ -0,0 +1,957 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ZodObject, ZodRawShape, ZodTypeAny, z } from 'zod';
+
+export interface Annotation {
+	type: string;
+	value: string;
+}
+export interface Usage {
+	input_tokens: number;
+	output_tokens: number;
+	cache_creation_input_tokens?: number;
+	cache_read_input_tokens?: number;
+	total_tokens?: number;
+}
+export interface ExtendedUsage extends Usage {
+	server_tool_use?: {
+		web_search_requests: number;
+	};
+	service_tier?: string;
+	cache_creation?: {
+		ephemeral_1h_input_tokens: number;
+		ephemeral_5m_input_tokens: number;
+	};
+}
+export interface ModelUsage {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadInputTokens: number;
+	cacheCreationInputTokens: number;
+	webSearchRequests: number;
+	contextWindow: number;
+}
+export interface CLIPermissionDenial {
+	tool_name: string;
+	tool_use_id: string;
+	tool_input: unknown;
+}
+export interface TextBlock {
+	type: "text";
+	text: string;
+	annotations?: Annotation[];
+}
+export interface ThinkingBlock {
+	type: "thinking";
+	thinking: string;
+	signature?: string;
+	annotations?: Annotation[];
+}
+export interface ToolUseBlock {
+	type: "tool_use";
+	id: string;
+	name: string;
+	input: unknown;
+	annotations?: Annotation[];
+}
+export interface ToolResultBlock {
+	type: "tool_result";
+	tool_use_id: string;
+	content?: string | ContentBlock[];
+	is_error?: boolean;
+	annotations?: Annotation[];
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock;
+export interface APIUserMessage {
+	role: "user";
+	content: string | ContentBlock[];
+}
+export interface APIAssistantMessage {
+	id: string;
+	type: "message";
+	role: "assistant";
+	model: string;
+	content: ContentBlock[];
+	stop_reason?: string | null;
+	usage: Usage;
+}
+export interface SDKUserMessage {
+	type: "user";
+	uuid?: string;
+	session_id: string;
+	message: APIUserMessage;
+	parent_tool_use_id: string | null;
+	options?: Record<string, unknown>;
+}
+export interface SDKAssistantMessage {
+	type: "assistant";
+	uuid: string;
+	session_id: string;
+	message: APIAssistantMessage;
+	parent_tool_use_id: string | null;
+}
+export interface SDKSystemMessage {
+	type: "system";
+	subtype: string;
+	uuid: string;
+	session_id: string;
+	data?: unknown;
+	cwd?: string;
+	tools?: string[];
+	mcp_servers?: Array<{
+		name: string;
+		status: string;
+	}>;
+	model?: string;
+	permission_mode?: string;
+	slash_commands?: string[];
+	qwen_code_version?: string;
+	output_style?: string;
+	agents?: string[];
+	skills?: string[];
+	capabilities?: Record<string, unknown>;
+	compact_metadata?: {
+		trigger: "manual" | "auto";
+		pre_tokens: number;
+	};
+}
+export interface SDKResultMessageSuccess {
+	type: "result";
+	subtype: "success";
+	uuid: string;
+	session_id: string;
+	is_error: false;
+	duration_ms: number;
+	duration_api_ms: number;
+	num_turns: number;
+	result: string;
+	usage: ExtendedUsage;
+	modelUsage?: Record<string, ModelUsage>;
+	permission_denials: CLIPermissionDenial[];
+	[key: string]: unknown;
+}
+export interface SDKResultMessageError {
+	type: "result";
+	subtype: "error_max_turns" | "error_during_execution";
+	uuid: string;
+	session_id: string;
+	is_error: true;
+	duration_ms: number;
+	duration_api_ms: number;
+	num_turns: number;
+	usage: ExtendedUsage;
+	modelUsage?: Record<string, ModelUsage>;
+	permission_denials: CLIPermissionDenial[];
+	error?: {
+		type?: string;
+		message: string;
+		[key: string]: unknown;
+	};
+	[key: string]: unknown;
+}
+export type SDKResultMessage = SDKResultMessageSuccess | SDKResultMessageError;
+export interface MessageStartStreamEvent {
+	type: "message_start";
+	message: {
+		id: string;
+		role: "assistant";
+		model: string;
+	};
+}
+export interface ContentBlockStartEvent {
+	type: "content_block_start";
+	index: number;
+	content_block: ContentBlock;
+}
+export type ContentBlockDelta = {
+	type: "text_delta";
+	text: string;
+} | {
+	type: "thinking_delta";
+	thinking: string;
+} | {
+	type: "input_json_delta";
+	partial_json: string;
+};
+export interface ContentBlockDeltaEvent {
+	type: "content_block_delta";
+	index: number;
+	delta: ContentBlockDelta;
+}
+export interface ContentBlockStopEvent {
+	type: "content_block_stop";
+	index: number;
+}
+export interface MessageStopStreamEvent {
+	type: "message_stop";
+}
+export type StreamEvent = MessageStartStreamEvent | ContentBlockStartEvent | ContentBlockDeltaEvent | ContentBlockStopEvent | MessageStopStreamEvent;
+export interface SDKPartialAssistantMessage {
+	type: "stream_event";
+	uuid: string;
+	session_id: string;
+	event: StreamEvent;
+	parent_tool_use_id: string | null;
+}
+export type PermissionMode = "default" | "plan" | "auto-edit" | "yolo";
+/**
+ * TODO: Align with `ToolCallConfirmationDetails`
+ */
+export interface PermissionSuggestion {
+	type: "allow" | "deny" | "modify";
+	label: string;
+	description?: string;
+	modifiedInput?: unknown;
+}
+export interface HookRegistration {
+	event: string;
+	callback_id: string;
+}
+export interface CLIControlInterruptRequest {
+	subtype: "interrupt";
+}
+export interface CLIControlPermissionRequest {
+	subtype: "can_use_tool";
+	tool_name: string;
+	tool_use_id: string;
+	input: unknown;
+	permission_suggestions: PermissionSuggestion[] | null;
+	blocked_path: string | null;
+}
+declare enum AuthProviderType {
+	DYNAMIC_DISCOVERY = "dynamic_discovery",
+	GOOGLE_CREDENTIALS = "google_credentials",
+	SERVICE_ACCOUNT_IMPERSONATION = "service_account_impersonation"
+}
+export interface MCPServerConfig {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	url?: string;
+	httpUrl?: string;
+	headers?: Record<string, string>;
+	tcp?: string;
+	timeout?: number;
+	trust?: boolean;
+	description?: string;
+	includeTools?: string[];
+	excludeTools?: string[];
+	extensionName?: string;
+	oauth?: Record<string, unknown>;
+	authProviderType?: AuthProviderType;
+	targetAudience?: string;
+	targetServiceAccount?: string;
+}
+/**
+ * SDK MCP Server configuration
+ *
+ * SDK MCP servers run in the SDK process and are connected via in-memory transport.
+ * Tool calls are routed through the control plane between SDK and CLI.
+ */
+export interface SDKMcpServerConfig {
+	/**
+	 * Type identifier for SDK MCP servers
+	 */
+	type: "sdk";
+	/**
+	 * Server name for identification and routing
+	 */
+	name: string;
+	/**
+	 * The MCP Server instance created by createSdkMcpServer()
+	 */
+	instance: McpServer;
+}
+/**
+ * Wire format for SDK MCP servers sent to the CLI
+ */
+export type WireSDKMcpServerConfig = Omit<SDKMcpServerConfig, "instance">;
+export interface CLIControlInitializeRequest {
+	subtype: "initialize";
+	hooks?: HookRegistration[] | null;
+	/**
+	 * SDK MCP servers config
+	 * These are MCP servers running in the SDK process, connected via control plane.
+	 * External MCP servers are configured separately in settings, not via initialization.
+	 */
+	sdkMcpServers?: Record<string, WireSDKMcpServerConfig>;
+	/**
+	 * External MCP servers that should be managed by the CLI.
+	 */
+	mcpServers?: Record<string, MCPServerConfig>;
+	agents?: SubagentConfig[];
+}
+export interface CLIControlSetPermissionModeRequest {
+	subtype: "set_permission_mode";
+	mode: PermissionMode;
+}
+export interface CLIHookCallbackRequest {
+	subtype: "hook_callback";
+	callback_id: string;
+	input: unknown;
+	tool_use_id: string | null;
+}
+export interface CLIControlMcpMessageRequest {
+	subtype: "mcp_message";
+	server_name: string;
+	message: {
+		jsonrpc?: string;
+		method: string;
+		params?: Record<string, unknown>;
+		id?: string | number | null;
+	};
+}
+export interface CLIControlSetModelRequest {
+	subtype: "set_model";
+	model: string;
+}
+export interface CLIControlMcpStatusRequest {
+	subtype: "mcp_server_status";
+}
+export interface CLIControlSupportedCommandsRequest {
+	subtype: "supported_commands";
+}
+export type ControlRequestPayload = CLIControlInterruptRequest | CLIControlPermissionRequest | CLIControlInitializeRequest | CLIControlSetPermissionModeRequest | CLIHookCallbackRequest | CLIControlMcpMessageRequest | CLIControlSetModelRequest | CLIControlMcpStatusRequest | CLIControlSupportedCommandsRequest;
+export interface CLIControlRequest {
+	type: "control_request";
+	request_id: string;
+	request: ControlRequestPayload;
+}
+export interface ControlResponse {
+	subtype: "success";
+	request_id: string;
+	response: unknown;
+}
+export interface ControlErrorResponse {
+	subtype: "error";
+	request_id: string;
+	error: string | {
+		message: string;
+		[key: string]: unknown;
+	};
+}
+export interface CLIControlResponse {
+	type: "control_response";
+	response: ControlResponse | ControlErrorResponse;
+}
+export interface ControlCancelRequest {
+	type: "control_cancel_request";
+	request_id?: string;
+}
+export type ControlMessage = CLIControlRequest | CLIControlResponse | ControlCancelRequest;
+/**
+ * Union of all SDK message types
+ */
+export type SDKMessage = SDKUserMessage | SDKAssistantMessage | SDKSystemMessage | SDKResultMessage | SDKPartialAssistantMessage;
+export declare function isSDKUserMessage(msg: any): msg is SDKUserMessage;
+export declare function isSDKAssistantMessage(msg: any): msg is SDKAssistantMessage;
+export declare function isSDKSystemMessage(msg: any): msg is SDKSystemMessage;
+export declare function isSDKResultMessage(msg: any): msg is SDKResultMessage;
+export declare function isSDKPartialAssistantMessage(msg: any): msg is SDKPartialAssistantMessage;
+export declare function isControlRequest(msg: any): msg is CLIControlRequest;
+export declare function isControlResponse(msg: any): msg is CLIControlResponse;
+export declare function isControlCancel(msg: any): msg is ControlCancelRequest;
+export type SubagentLevel = "session";
+export interface ModelConfig {
+	model?: string;
+	temp?: number;
+	top_p?: number;
+}
+export interface RunConfig {
+	max_time_minutes?: number;
+	max_turns?: number;
+}
+export interface SubagentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	systemPrompt: string;
+	level: SubagentLevel;
+	filePath?: string;
+	modelConfig?: Partial<ModelConfig>;
+	runConfig?: Partial<RunConfig>;
+	color?: string;
+	readonly isBuiltin?: boolean;
+}
+/**
+ * Transport interface for SDK-CLI communication
+ *
+ * The Transport abstraction enables communication between SDK and CLI via different mechanisms:
+ * - ProcessTransport: Local subprocess via stdin/stdout (initial implementation)
+ * - HttpTransport: Remote CLI via HTTP (future)
+ * - WebSocketTransport: Remote CLI via WebSocket (future)
+ */
+export interface Transport {
+	close(): Promise<void>;
+	waitForExit(): Promise<void>;
+	write(message: string): void;
+	readMessages(): AsyncGenerator<unknown, void, unknown>;
+	readonly isReady: boolean;
+	readonly exitError: Error | null;
+}
+export type ToolInput = Record<string, unknown>;
+export type CanUseTool = (toolName: string, input: ToolInput, options: {
+	signal: AbortSignal;
+	suggestions?: PermissionSuggestion[] | null;
+}) => Promise<PermissionResult>;
+export type PermissionResult = {
+	behavior: "allow";
+	updatedInput: ToolInput;
+} | {
+	behavior: "deny";
+	message: string;
+	interrupt?: boolean;
+};
+/**
+ * OAuth configuration for MCP servers
+ */
+export interface McpOAuthConfig {
+	enabled?: boolean;
+	clientId?: string;
+	clientSecret?: string;
+	scopes?: string[];
+	redirectUri?: string;
+	authorizationUrl?: string;
+	tokenUrl?: string;
+	audiences?: string[];
+	tokenParamName?: string;
+	registrationUrl?: string;
+}
+/**
+ * Auth provider type for MCP servers
+ */
+export type McpAuthProviderType = "dynamic_discovery" | "google_credentials" | "service_account_impersonation";
+/**
+ * CLI MCP Server configuration
+ *
+ * Supports multiple transport types:
+ * - stdio: command, args, env, cwd
+ * - SSE: url
+ * - Streamable HTTP: httpUrl, headers
+ * - WebSocket: tcp
+ *
+ * This interface aligns with MCPServerConfig in @qwen-code/qwen-code-core.
+ */
+export interface CLIMcpServerConfig {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	url?: string;
+	httpUrl?: string;
+	headers?: Record<string, string>;
+	tcp?: string;
+	timeout?: number;
+	trust?: boolean;
+	description?: string;
+	includeTools?: string[];
+	excludeTools?: string[];
+	extensionName?: string;
+	oauth?: McpOAuthConfig;
+	authProviderType?: McpAuthProviderType;
+	/** targetAudience format: CLIENT_ID.apps.googleusercontent.com */
+	targetAudience?: string;
+	/** targetServiceAccount format: <service-account-name>@<project-num>.iam.gserviceaccount.com */
+	targetServiceAccount?: string;
+}
+/**
+ * Unified MCP Server configuration
+ *
+ * Supports both external MCP servers (stdio/SSE/HTTP/WebSocket) and SDK-embedded MCP servers.
+ *
+ * @example External MCP server (stdio)
+ * ```typescript
+ * mcpServers: {
+ *   'my-server': { command: 'node', args: ['server.js'] }
+ * }
+ * ```
+ *
+ * @example External MCP server (SSE)
+ * ```typescript
+ * mcpServers: {
+ *   'remote-server': { url: 'http://localhost:3000/sse' }
+ * }
+ * ```
+ *
+ * @example External MCP server (Streamable HTTP)
+ * ```typescript
+ * mcpServers: {
+ *   'http-server': { httpUrl: 'http://localhost:3000/mcp', headers: { 'Authorization': 'Bearer token' } }
+ * }
+ * ```
+ *
+ * @example SDK MCP server
+ * ```typescript
+ * const server = createSdkMcpServer('weather', '1.0.0', [weatherTool]);
+ * mcpServers: {
+ *   'weather': { type: 'sdk', name: 'weather', instance: server }
+ * }
+ * ```
+ */
+export type McpServerConfig = CLIMcpServerConfig | SDKMcpServerConfig;
+/**
+ * Type guard to check if a config is an SDK MCP server
+ */
+export declare function isSdkMcpServerConfig(config: McpServerConfig): config is SDKMcpServerConfig;
+/**
+ * Configuration options for creating a query session with the Qwen CLI.
+ */
+export interface QueryOptions {
+	/**
+	 * The working directory for the query session.
+	 * This determines the context in which file operations and commands are executed.
+	 * @default process.cwd()
+	 */
+	cwd?: string;
+	/**
+	 * The AI model to use for the query session.
+	 * This takes precedence over the environment variables `OPENAI_MODEL` and `QWEN_MODEL`
+	 * @example 'qwen-max', 'qwen-plus', 'qwen-turbo'
+	 */
+	model?: string;
+	/**
+	 * Path to the Qwen CLI executable or runtime specification.
+	 *
+	 * Supports multiple formats:
+	 * - 'qwen' -> native binary (auto-detected from PATH)
+	 * - '/path/to/qwen' -> native binary (explicit path)
+	 * - '/path/to/cli.js' -> Node.js bundle (default for .js files)
+	 * - '/path/to/index.ts' -> TypeScript source (requires tsx)
+	 * - 'bun:/path/to/cli.js' -> Force Bun runtime
+	 * - 'node:/path/to/cli.js' -> Force Node.js runtime
+	 * - 'tsx:/path/to/index.ts' -> Force tsx runtime
+	 * - 'deno:/path/to/cli.ts' -> Force Deno runtime
+	 *
+	 * If not provided, the SDK will auto-detect the native binary in this order:
+	 * 1. QWEN_CODE_CLI_PATH environment variable
+	 * 2. ~/.volta/bin/qwen
+	 * 3. ~/.npm-global/bin/qwen
+	 * 4. /usr/local/bin/qwen
+	 * 5. ~/.local/bin/qwen
+	 * 6. ~/node_modules/.bin/qwen
+	 * 7. ~/.yarn/bin/qwen
+	 *
+	 * The .ts files are only supported for debugging purposes.
+	 *
+	 * @example 'qwen'
+	 * @example '/usr/local/bin/qwen'
+	 * @example 'tsx:/path/to/packages/cli/src/index.ts'
+	 */
+	pathToQwenExecutable?: string;
+	/**
+	 * Environment variables to pass to the Qwen CLI process.
+	 * These variables will be merged with the current process environment.
+	 */
+	env?: Record<string, string>;
+	/**
+	 * Permission mode controlling how the SDK handles tool execution approval.
+	 *
+	 * - 'default': Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`.
+	 *   Read-only tools execute without confirmation.
+	 * - 'plan': Blocks all write tools, instructing AI to present a plan first.
+	 *   Read-only tools execute normally.
+	 * - 'auto-edit': Auto-approve edit tools (edit, write_file) while other tools require confirmation.
+	 * - 'yolo': All tools execute automatically without confirmation.
+	 *
+	 * **Priority Chain (highest to lowest):**
+	 * 1. `excludeTools` - Blocks tools completely (returns permission error)
+	 * 2. `permissionMode: 'plan'` - Blocks non-read-only tools (except exit_plan_mode)
+	 * 3. `permissionMode: 'yolo'` - Auto-approves all tools
+	 * 4. `allowedTools` - Auto-approves matching tools
+	 * 5. `canUseTool` callback - Custom approval logic
+	 * 6. Default behavior - Auto-deny in SDK mode
+	 *
+	 * @default 'default'
+	 * @see canUseTool For custom permission handling
+	 * @see allowedTools For auto-approving specific tools
+	 * @see excludeTools For blocking specific tools
+	 */
+	permissionMode?: "default" | "plan" | "auto-edit" | "yolo";
+	/**
+	 * Custom permission handler for tool execution approval.
+	 *
+	 * This callback is invoked when a tool requires confirmation and allows you to
+	 * programmatically approve or deny execution. It acts as a fallback after
+	 * `allowedTools` check but before default denial.
+	 *
+	 * **When is this called?**
+	 * - Only for tools requiring confirmation (write operations, shell commands, etc.)
+	 * - After `excludeTools` and `allowedTools` checks
+	 * - Not called in 'yolo' mode or 'plan' mode
+	 * - Not called for tools already in `allowedTools`
+	 *
+	 * **Usage with permissionMode:**
+	 * - 'default': Invoked for all write tools not in `allowedTools`; if not provided, auto-denied.
+	 * - 'auto-edit': Invoked for non-edit tools (edit/write_file auto-approved); if not provided, auto-denied.
+	 * - 'plan': Not invoked; write tools are blocked by plan mode.
+	 * - 'yolo': Not invoked; all tools auto-approved.
+	 *
+	 * @see allowedTools For auto-approving tools without callback
+	 */
+	canUseTool?: CanUseTool;
+	/**
+	 * MCP (Model Context Protocol) servers to connect to.
+	 *
+	 * Supports both external MCP servers and SDK-embedded MCP servers:
+	 *
+	 * **External MCP servers** - Run in separate processes, connected via stdio/SSE/HTTP:
+	 * ```typescript
+	 * mcpServers: {
+	 *   'stdio-server': { command: 'node', args: ['server.js'], env: { PORT: '3000' } },
+	 *   'sse-server': { url: 'http://localhost:3000/sse' },
+	 *   'http-server': { httpUrl: 'http://localhost:3000/mcp' }
+	 * }
+	 * ```
+	 *
+	 * **SDK MCP servers** - Run in the SDK process, connected via in-memory transport:
+	 * ```typescript
+	 * const myTool = tool({
+	 *   name: 'my_tool',
+	 *   description: 'My custom tool',
+	 *   inputSchema: { type: 'object', properties: { input: { type: 'string' } } },
+	 *   handler: async (input) => ({ result: input.input.toUpperCase() }),
+	 * });
+	 *
+	 * const server = createSdkMcpServer('my-server', '1.0.0', [myTool]);
+	 *
+	 * mcpServers: {
+	 *   'my-server': { type: 'sdk', name: 'my-server', instance: server }
+	 * }
+	 * ```
+	 */
+	mcpServers?: Record<string, McpServerConfig>;
+	/**
+	 * AbortController to cancel the query session.
+	 * Call abortController.abort() to terminate the session and cleanup resources.
+	 * Remember to handle the AbortError when the session is aborted.
+	 */
+	abortController?: AbortController;
+	/**
+	 * Enable debug mode for verbose logging.
+	 * When true, additional diagnostic information will be output.
+	 * Use this with `logLevel` to control the verbosity of the logs.
+	 * @default false
+	 */
+	debug?: boolean;
+	/**
+	 * Custom handler for stderr output from the Qwen CLI process.
+	 * Use this to capture and process error messages or diagnostic output.
+	 */
+	stderr?: (message: string) => void;
+	/**
+	 * Logging level for the SDK.
+	 * Controls the verbosity of log messages output by the SDK.
+	 * @default 'info'
+	 */
+	logLevel?: "debug" | "info" | "warn" | "error";
+	/**
+	 * Maximum number of conversation turns before the session automatically terminates.
+	 * A turn consists of a user message and an assistant response.
+	 * @default -1 (unlimited)
+	 */
+	maxSessionTurns?: number;
+	/**
+	 * Equivalent to `tool.core` in settings.json.
+	 * List of core tools to enable for the session.
+	 * If specified, only these tools will be available to the AI.
+	 * @example ['read_file', 'write_file', 'run_terminal_cmd']
+	 */
+	coreTools?: string[];
+	/**
+	 * Equivalent to `tool.exclude` in settings.json.
+	 * List of tools to exclude from the session.
+	 *
+	 * **Behavior:**
+	 * - Excluded tools return a permission error immediately when invoked
+	 * - Takes highest priority - overrides all other permission settings
+	 * - Tools will not be available to the AI, even if in `coreTools` or `allowedTools`
+	 *
+	 * **Pattern matching:**
+	 * - Tool name: `'write_file'`, `'run_shell_command'`
+	 * - Tool class: `'WriteTool'`, `'ShellTool'`
+	 * - Shell command prefix: `'ShellTool(git commit)'` (matches commands starting with "git commit")
+	 *
+	 * @example ['run_terminal_cmd', 'delete_file', 'ShellTool(rm )']
+	 * @see allowedTools For allowing specific tools
+	 */
+	excludeTools?: string[];
+	/**
+	 * Equivalent to `tool.allowed` in settings.json.
+	 * List of tools that are allowed to run without confirmation.
+	 *
+	 * **Behavior:**
+	 * - Matching tools bypass `canUseTool` callback and execute automatically
+	 * - Only applies when tool requires confirmation (write operations, shell commands)
+	 * - Checked after `excludeTools` but before `canUseTool` callback
+	 * - Does not override `permissionMode: 'plan'` (plan mode blocks all write tools)
+	 * - Has no effect in `permissionMode: 'yolo'` (already auto-approved)
+	 *
+	 * **Pattern matching:**
+	 * - Tool name: `'write_file'`, `'run_shell_command'`
+	 * - Tool class: `'WriteTool'`, `'ShellTool'`
+	 * - Shell command prefix: `'ShellTool(git status)'` (matches commands starting with "git status")
+	 *
+	 * **Use cases:**
+	 * - Auto-approve safe shell commands: `['ShellTool(git status)', 'ShellTool(ls)']`
+	 * - Auto-approve specific tools: `['write_file', 'edit']`
+	 * - Combine with `permissionMode: 'default'` to selectively auto-approve tools
+	 *
+	 * @example ['read_file', 'ShellTool(git status)', 'ShellTool(npm test)']
+	 * @see canUseTool For custom approval logic
+	 * @see excludeTools For blocking specific tools
+	 */
+	allowedTools?: string[];
+	/**
+	 * Authentication type for the AI service.
+	 * - 'openai': Use OpenAI-compatible authentication
+	 * - 'qwen-oauth': Use Qwen OAuth authentication
+	 *
+	 * Though we support 'qwen-oauth', it's not recommended to use it in the SDK.
+	 * Because the credentials are stored in `~/.qwen` and may need to refresh periodically.
+	 */
+	authType?: "openai" | "qwen-oauth";
+	/**
+	 * Configuration for subagents that can be invoked during the session.
+	 * Subagents are specialized AI agents that can handle specific tasks or domains.
+	 * The invocation is marked as a `task` tool use with the name of agent and a tool_use_id.
+	 * The tool use of these agent is marked with the parent_tool_use_id of the `task` tool use.
+	 */
+	agents?: SubagentConfig[];
+	/**
+	 * Include partial messages in the response stream.
+	 * When true, the SDK will emit incomplete messages as they are being generated,
+	 * allowing for real-time streaming of the AI's response.
+	 * @default false
+	 */
+	includePartialMessages?: boolean;
+	/**
+	 * Timeout configuration for various SDK operations.
+	 * All values are in milliseconds.
+	 */
+	timeout?: {
+		/**
+		 * Timeout for the `canUseTool` callback.
+		 * If the callback doesn't resolve within this time, the permission request
+		 * will be denied with a timeout error (fail-safe behavior).
+		 * @default 60000 (1 minute)
+		 */
+		canUseTool?: number;
+		/**
+		 * Timeout for SDK MCP tool calls.
+		 * This applies to tool calls made to SDK-embedded MCP servers.
+		 * @default 60000 (1 minute)
+		 */
+		mcpRequest?: number;
+		/**
+		 * Timeout for SDK→CLI control requests.
+		 * This applies to internal control operations like initialize, interrupt,
+		 * setPermissionMode, setModel, etc.
+		 * @default 60000 (1 minute)
+		 */
+		controlRequest?: number;
+		/**
+		 * Timeout for waiting before closing CLI's stdin after user messages are sent.
+		 * In multi-turn mode with SDK MCP servers, after all user messages are processed,
+		 * the SDK waits for the first result message to ensure all initialization
+		 * (control responses, MCP server setup, etc.) is complete before closing stdin.
+		 * This timeout is a fallback to avoid hanging indefinitely.
+		 * @default 60000 (1 minute)
+		 */
+		streamClose?: number;
+	};
+}
+export declare class Query implements AsyncIterable<SDKMessage> {
+	private transport;
+	private options;
+	private sessionId;
+	private inputStream;
+	private sdkMessages;
+	private abortController;
+	private pendingControlRequests;
+	private pendingMcpResponses;
+	private sdkMcpTransports;
+	private sdkMcpServers;
+	readonly initialized: Promise<void>;
+	private closed;
+	private messageRouterStarted;
+	private firstResultReceivedPromise?;
+	private firstResultReceivedResolve?;
+	private readonly isSingleTurn;
+	constructor(transport: Transport, options: QueryOptions, singleTurn?: boolean);
+	private initializeSdkMcpServers;
+	/**
+	 * Handle response messages from SDK MCP servers
+	 *
+	 * When an MCP server sends a response via transport.send(), this callback
+	 * routes it back to the pending request that's waiting for it.
+	 */
+	private handleMcpServerResponse;
+	/**
+	 * Get SDK MCP servers config for CLI initialization
+	 *
+	 * Only SDK servers are sent in the initialize request.
+	 */
+	private getSdkMcpServersForCli;
+	/**
+	 * Get external MCP servers (non-SDK) that should be managed by the CLI
+	 */
+	private getMcpServersForCli;
+	private initialize;
+	private startMessageRouter;
+	private routeMessage;
+	private handleControlRequest;
+	private handlePermissionRequest;
+	private handleMcpMessage;
+	private handleMcpRequest;
+	private handleControlResponse;
+	private handleControlCancelRequest;
+	private sendControlRequest;
+	private sendControlResponse;
+	close(): Promise<void>;
+	private readSdkMessages;
+	next(...args: [
+	] | [
+		unknown
+	]): Promise<IteratorResult<SDKMessage>>;
+	return(value?: unknown): Promise<IteratorResult<SDKMessage>>;
+	throw(e?: unknown): Promise<IteratorResult<SDKMessage>>;
+	[Symbol.asyncIterator](): AsyncIterator<SDKMessage>;
+	streamInput(messages: AsyncIterable<SDKUserMessage>): Promise<void>;
+	endInput(): void;
+	interrupt(): Promise<void>;
+	setPermissionMode(mode: string): Promise<void>;
+	setModel(model: string): Promise<void>;
+	/**
+	 * Get list of control commands supported by the CLI
+	 *
+	 * @returns Promise resolving to list of supported command names
+	 * @throws Error if query is closed
+	 */
+	supportedCommands(): Promise<Record<string, unknown> | null>;
+	/**
+	 * Get the status of MCP servers
+	 *
+	 * @returns Promise resolving to MCP server status information
+	 * @throws Error if query is closed
+	 */
+	mcpServerStatus(): Promise<Record<string, unknown> | null>;
+	getSessionId(): string;
+	isClosed(): boolean;
+}
+export declare function query({ prompt, options, }: {
+	/**
+	 * The prompt to send to the Qwen Code CLI process.
+	 * - `string` for single-turn query,
+	 * - `AsyncIterable<SDKUserMessage>` for multi-turn query.
+	 *
+	 * The transport will remain open until the prompt is done.
+	 */
+	prompt: string | AsyncIterable<SDKUserMessage>;
+	/**
+	 * Configuration options for the query.
+	 */
+	options?: QueryOptions;
+}): Query;
+export declare class AbortError extends Error {
+	constructor(message?: string);
+}
+export declare function isAbortError(error: unknown): error is AbortError;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LoggerConfig {
+	debug?: boolean;
+	stderr?: (message: string) => void;
+	logLevel?: LogLevel;
+}
+export interface ScopedLogger {
+	debug(message: string, ...args: unknown[]): void;
+	info(message: string, ...args: unknown[]): void;
+	warn(message: string, ...args: unknown[]): void;
+	error(message: string, ...args: unknown[]): void;
+}
+export declare class SdkLogger {
+	private static config;
+	private static effectiveLevel;
+	static configure(config: LoggerConfig): void;
+	private static determineLogLevel;
+	private static isValidLogLevel;
+	private static shouldLog;
+	private static formatTimestamp;
+	private static formatMessage;
+	private static log;
+	static createLogger(scope: string): ScopedLogger;
+	static getEffectiveLevel(): LogLevel;
+}
+export type CallToolResult = z.infer<typeof CallToolResultSchema>;
+/**
+ * SDK MCP Tool Definition with Zod schema type inference
+ */
+export type SdkMcpToolDefinition<Schema extends ZodRawShape = ZodRawShape> = {
+	name: string;
+	description: string;
+	inputSchema: Schema;
+	handler: (args: z.infer<ZodObject<Schema, "strip", ZodTypeAny>>, extra: unknown) => Promise<CallToolResult>;
+};
+/**
+ * Create an SDK MCP tool definition with Zod schema inference
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { tool } from '@qwen-code/sdk';
+ *
+ * const calculatorTool = tool(
+ *   'calculate_sum',
+ *   'Calculate the sum of two numbers',
+ *   { a: z.number(), b: z.number() },
+ *   async (args) => {
+ *     // args is inferred as { a: number, b: number }
+ *     return { content: [{ type: 'text', text: String(args.a + args.b) }] };
+ *   }
+ * );
+ * ```
+ */
+export declare function tool<Schema extends ZodRawShape>(name: string, description: string, inputSchema: Schema, handler: (args: z.infer<ZodObject<Schema, "strip", ZodTypeAny>>, extra: unknown) => Promise<CallToolResult>): SdkMcpToolDefinition<Schema>;
+/**
+ * Options for creating an SDK MCP server
+ */
+export type CreateSdkMcpServerOptions = {
+	name: string;
+	version?: string;
+	tools?: Array<SdkMcpToolDefinition<any>>;
+};
+/**
+ * SDK MCP Server configuration with instance
+ */
+export type McpSdkServerConfigWithInstance = {
+	type: "sdk";
+	name: string;
+	instance: McpServer;
+};
+/**
+ * Creates an MCP server instance that can be used with the SDK transport.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { tool, createSdkMcpServer } from '@qwen-code/sdk';
+ *
+ * const calculatorTool = tool(
+ *   'calculate_sum',
+ *   'Add two numbers',
+ *   { a: z.number(), b: z.number() },
+ *   async (args) => ({ content: [{ type: 'text', text: String(args.a + args.b) }] })
+ * );
+ *
+ * const server = createSdkMcpServer({
+ *   name: 'calculator',
+ *   version: '1.0.0',
+ *   tools: [calculatorTool],
+ * });
+ * ```
+ */
+export declare function createSdkMcpServer(options: CreateSdkMcpServerOptions): McpSdkServerConfigWithInstance;
+
+export {};