From a4ffe9d072aa25214dff84a48468097811675c38 Mon Sep 17 00:00:00 2001 From: juhuan <46651841+juhuan@users.noreply.github.com> Date: Wed, 8 Jul 2026 00:00:43 +0800 Subject: [PATCH] feat(sdk): add extra_args option to both SDKs Add `extra_args` (Python) / `extraArgs` (TypeScript) option that allows passing arbitrary CLI flags to the qwen process. This is an escape hatch for CLI features not explicitly supported by the SDK. Python SDK: - `extra_args: list[str] | None` in QueryOptions - Appended to CLI arguments in build_cli_arguments - Validates that SDK-managed flags (--input-format, --output-format, --channel) are not included TypeScript SDK: - `extraArgs?: string[]` in TransportOptions and QueryOptions - Appended in ProcessTransport.buildCliArguments --- .../sdk-python/src/qwen_code_sdk/transport.py | 3 +++ packages/sdk-python/src/qwen_code_sdk/types.py | 3 +++ .../sdk-python/src/qwen_code_sdk/validation.py | 13 +++++++++++++ packages/sdk-typescript/src/query/createQuery.ts | 1 + .../src/transport/ProcessTransport.ts | 4 ++++ .../src/types/queryOptionsSchema.ts | 1 + packages/sdk-typescript/src/types/types.ts | 15 +++++++++++++++ 7 files changed, 40 insertions(+) diff --git a/packages/sdk-python/src/qwen_code_sdk/transport.py b/packages/sdk-python/src/qwen_code_sdk/transport.py index 8542364943f..346032e2da9 100644 --- a/packages/sdk-python/src/qwen_code_sdk/transport.py +++ b/packages/sdk-python/src/qwen_code_sdk/transport.py @@ -240,4 +240,7 @@ def build_cli_arguments(options: QueryOptions) -> list[str]: elif options.session_id: args.extend(["--session-id", options.session_id]) + if options.extra_args: + args.extend(options.extra_args) + return args diff --git a/packages/sdk-python/src/qwen_code_sdk/types.py b/packages/sdk-python/src/qwen_code_sdk/types.py index 3d8ec72038e..5f5f686ab4d 100644 --- a/packages/sdk-python/src/qwen_code_sdk/types.py +++ b/packages/sdk-python/src/qwen_code_sdk/types.py @@ -114,6 +114,7 @@ class QueryOptionsDict(TypedDict, total=False): timeout: TimeoutOptionsDict mcp_servers: dict[str, dict[str, Any]] stderr: Callable[[str], None] + extra_args: list[str] @dataclass @@ -139,6 +140,7 @@ class QueryOptions: timeout: TimeoutOptions = TimeoutOptions() mcp_servers: dict[str, dict[str, Any]] | None = None stderr: Callable[[str], None] | None = None + extra_args: list[str] | None = None @classmethod def from_mapping(cls, value: Mapping[str, Any] | None) -> QueryOptions: @@ -183,6 +185,7 @@ def from_mapping(cls, value: Mapping[str, Any] | None) -> QueryOptions: Callable[[str], None] | None, _as_optional_callable(data, "stderr"), ), + extra_args=_as_optional_str_list(data, "extra_args"), ) diff --git a/packages/sdk-python/src/qwen_code_sdk/validation.py b/packages/sdk-python/src/qwen_code_sdk/validation.py index f19fe4cfba6..f52fe38d044 100644 --- a/packages/sdk-python/src/qwen_code_sdk/validation.py +++ b/packages/sdk-python/src/qwen_code_sdk/validation.py @@ -64,6 +64,19 @@ def validate_query_options(options: QueryOptions) -> None: ): raise ValidationError("path_to_qwen_executable cannot be empty") + if options.extra_args: + _CONFLICTING_FLAGS = { + "--input-format", + "--output-format", + "--channel", + } + for arg in options.extra_args: + if arg in _CONFLICTING_FLAGS: + raise ValidationError( + f"extra_args cannot include '{arg}' — " + "it is managed by the SDK" + ) + if options.mcp_servers: raise ValidationError( "mcp_servers is not supported in Python SDK v1. " diff --git a/packages/sdk-typescript/src/query/createQuery.ts b/packages/sdk-typescript/src/query/createQuery.ts index 42d332b15f1..a7430135eb3 100644 --- a/packages/sdk-typescript/src/query/createQuery.ts +++ b/packages/sdk-typescript/src/query/createQuery.ts @@ -70,6 +70,7 @@ export function query({ includePartialMessages: options.includePartialMessages, resume: options.resume, sessionId, + extraArgs: options.extraArgs, }); const queryOptions: QueryOptions = { diff --git a/packages/sdk-typescript/src/transport/ProcessTransport.ts b/packages/sdk-typescript/src/transport/ProcessTransport.ts index 1a63e96d550..f9d1854732f 100644 --- a/packages/sdk-typescript/src/transport/ProcessTransport.ts +++ b/packages/sdk-typescript/src/transport/ProcessTransport.ts @@ -335,6 +335,10 @@ export class ProcessTransport implements Transport { args.push('--session-id', this.options.sessionId); } + if (this.options.extraArgs && this.options.extraArgs.length > 0) { + args.push(...this.options.extraArgs); + } + return args; } diff --git a/packages/sdk-typescript/src/types/queryOptionsSchema.ts b/packages/sdk-typescript/src/types/queryOptionsSchema.ts index 702ea1c632d..a0dc78c8519 100644 --- a/packages/sdk-typescript/src/types/queryOptionsSchema.ts +++ b/packages/sdk-typescript/src/types/queryOptionsSchema.ts @@ -182,5 +182,6 @@ export const QueryOptionsSchema = z resume: z.string().optional(), sessionId: z.string().optional(), timeout: TimeoutConfigSchema.optional(), + extraArgs: z.array(z.string()).optional(), }) .strict(); diff --git a/packages/sdk-typescript/src/types/types.ts b/packages/sdk-typescript/src/types/types.ts index 3a7e26ee0aa..b90e0e143d6 100644 --- a/packages/sdk-typescript/src/types/types.ts +++ b/packages/sdk-typescript/src/types/types.ts @@ -46,6 +46,13 @@ export type TransportOptions = { * When resume is provided, this should match the resume ID. */ sessionId?: string; + /** + * Additional CLI arguments to pass to the qwen process. + * Escape hatch for flags not explicitly supported by the SDK. + * Cannot include --input-format, --output-format, or --channel + * (managed by the SDK). + */ + extraArgs?: string[]; }; export interface QuerySystemPromptPreset { @@ -503,4 +510,12 @@ export interface QueryOptions { */ streamClose?: number; }; + + /** + * Additional CLI arguments to pass to the qwen process. + * Escape hatch for flags not explicitly supported by the SDK. + * Cannot include --input-format, --output-format, or --channel + * (managed by the SDK). + */ + extraArgs?: string[]; }