@qoder-ai/qoder-agent-sdk 1.0.17 → 1.0.20

package/README.md

@@ -23,16 +23,10 @@ installed if your application uses SDK tools or MCP integration.
 
 ## Runtime Behavior
 
-The standard npm package keeps the existing process runtime behavior:
-`query()` launches `qodercli` as a child process by default. During
-`npm install`, the postinstall script downloads the platform-specific CLI into
-`dist/_bundled`.
-
-Packages built with the Worker runtime bundle bake that choice into the SDK:
-their default `query()` transport is `WorkerTransport.default`, and install
-does not download the process CLI unless `QODER_INSTALL_BUNDLED_CLI=1` is set.
-Worker runtime assets can either be packaged into the tarball or downloaded by
-postinstall, depending on the release pipeline.
+The npm package uses `WorkerTransport.default` for `query()` by default. During
+`npm install`, its postinstall script downloads the Worker runtime selected by
+the package's pinned CLI version into `dist/_worker`. It does not download the
+process CLI unless `QODER_INSTALL_BUNDLED_CLI=1` is set.
 
 You can still select a transport explicitly on the same `query()` entry:
 
@@ -52,17 +46,15 @@ const q = query({
 });
 ```
 
-When the package includes `dist/_worker/qoder-worker-runtime.obf.mjs`, the
-worker transport uses that embedded runtime; otherwise set
+The worker transport uses the runtime installed at
+`dist/_worker/qoder-worker-runtime.obf.mjs`. You can instead set
 `QODER_WORKER_RUNTIME_PATH` or pass
 `new WorkerTransport({ pathToQoderWorkerRuntime })`.
 
-Worker-bundled packages include a `dist/runtime-manifest.json` that records the
-default runtime and whether the Worker runtime is packaged or installed by
-postinstall. Install-delivered packages can also pin the qodercli Worker runtime
-archive URL in that manifest; the SDK package itself does not need to host a
-copy of the archive. The presence of `dist/_worker` is used as an integrity
-check after installation, not as the mode selector.
+The package includes a `dist/runtime-manifest.json` that records the default
+runtime and pins the qodercli Worker runtime archive URL. The SDK package itself
+does not need to host a copy of the archive. The presence of `dist/_worker` is
+used as an integrity check after installation, not as the mode selector.
 
 The packaged Worker runtime is built as a self-contained universal profile by
 default. Runtime assets such as native keychain bindings, PTY bindings, image
@@ -86,11 +78,16 @@ export QODERCLI_PATH=/absolute/path/to/qodercli
 export QODER_WORKER_RUNTIME_PATH=/absolute/path/to/qoder-worker-runtime.obf.mjs
 ```
 
-`query()` is the only query entry point. Standard packages default to process;
-Worker-bundled packages default to Worker. Pass `transport: ProcessTransport.default`,
+`query()` is the only query entry point and defaults to Worker. Pass
+`transport: ProcessTransport.default`,
 `transport: WorkerTransport.default`, or a custom transport provider when a
 single call needs to override the package default.
 
+`pathToQoderCLIExecutable` accepts either local runtime form. Native binaries
+and ordinary CLI `.js`/`.mjs` entries use the process transport; recognized
+`qoder-worker-runtime*.mjs` entries use the Worker transport. An explicit
+`transport` provider always takes precedence over automatic path selection.
+
 ## Authentication
 
 Every SDK query needs an explicit authentication option.
@@ -146,7 +143,7 @@ short-lived SATs for qodercli. See the
 [host callback example](examples/service-account-token-demo/demo.mjs) for a
 complete Token exchange and query. To reuse a signed-in developer
 workstation, use `qodercliAuth()`. See the
-[SDK authentication guide](docs/public/en/cli/sdk/authentication.mdx) for
+[SDK authentication guide](docs/public/global/cli/sdk/authentication.mdx) for
 complete setup instructions and security guidance.
 
 ## Quick Start

package/dist/auth.d.ts

@@ -1,6 +1,6 @@
 import type { AuthOptions, FetchJobToken, JobTokenAuthOptions, ServiceAccountAuthOptions, ServiceAccountCredentials } from './types/auth.js';
-export declare const DEFAULT_ACCESS_TOKEN_ENV_VAR = "QODER_PERSONAL_ACCESS_TOKEN";
-export declare const DEFAULT_SERVICE_ACCOUNT_ENV_VAR = "QODER_SERVICE_ACCOUNT_KEY";
+export declare const DEFAULT_ACCESS_TOKEN_ENV_VAR: string;
+export declare const DEFAULT_SERVICE_ACCOUNT_ENV_VAR: string;
 export declare function accessToken(token: string): AuthOptions;
 export declare function accessTokenFromEnv(envVar?: string): AuthOptions;
 export declare function qodercliAuth(): AuthOptions;

package/dist/core/brand.d.ts

@@ -0,0 +1,22 @@
+export type SdkBrand = 'global' | 'cn';
+export declare const SDK_BRAND: SdkBrand;
+export declare const IS_CN_SDK: boolean;
+export declare const SDK_BRAND_CONFIG: {
+    productName: string;
+    packageName: string;
+    cliCommands: readonly ["qoderclicn", "qodercn"];
+    configDirName: string;
+    configDirEnv: string;
+    cliHomeEnv: string;
+    accessTokenEnv: string;
+    serviceAccountEnv: string;
+} | {
+    productName: string;
+    packageName: string;
+    cliCommands: readonly ["qodercli", "qoder"];
+    configDirName: string;
+    configDirEnv: string;
+    cliHomeEnv: string;
+    accessTokenEnv: string;
+    serviceAccountEnv: string;
+};

package/dist/core/constants.d.ts

@@ -21,10 +21,7 @@ export declare const CLOSE_GRACE_MS = 2000;
  * If the process hasn't exited after SIGTERM within this window, force-kill it.
  */
 export declare const KILL_GRACE_MS = 5000;
-/**
- * Current SDK version, sent to CLI as QODER_AGENT_SDK_VERSION environment variable.
- */
-export declare const SDK_VERSION = "1.0.16";
+export declare const SDK_VERSION: string;
 /**
  * Value for the `--permission-prompt-tool` CLI flag.
  *
@@ -44,10 +41,18 @@ export declare const CLI_EXIT_CODE_AUTH_ERROR = 41;
  *
  * Keep this list explicit so new qodercli built-ins do not automatically
  * become SDK-visible. Goal, cron, workflow, plan-mode transition, Bash PTY,
- * worktree, tracker, topic, and task-control tools remain opt-in via
+ * worktree, topic, and background-task control tools remain opt-in via
  * `options.tools`.
  */
-export declare const SDK_DEFAULT_TOOLS: readonly ["Agent", "AskUserQuestion", "Bash", "Edit", "Glob", "Grep", "ImageGen", "ImageSearch", "NotebookEdit", "Read", "Skill", "TodoWrite", "WebFetch", "WebSearch", "Write"];
+export declare const SDK_DEFAULT_TOOLS: readonly ["Agent", "AskUserQuestion", "Bash", "Edit", "Glob", "Grep", "ImageGen", "ImageSearch", "NotebookEdit", "Read", "Skill", "TaskCreate", "TaskGet", "TaskUpdate", "TaskList", "WebFetch", "WebSearch", "Write"];
+export declare const SDK_TASK_TOOLS: readonly ["TaskCreate", "TaskGet", "TaskUpdate", "TaskList"];
+/**
+ * Resolve the SDK's curated default tool surface against qodercli's Task
+ * feature flag. qodercli replaces the persistent Task tools with TodoWrite
+ * when QODER_FEATURE_TASKS is explicitly disabled, so the SDK must make the
+ * same replacement before it writes its explicit --tools allowlist.
+ */
+export declare function resolveSdkDefaultTools(env: Record<string, string | undefined>): string[];
 /**
  * Tool names with SDK-side enrichment. Tracked as constants so callers and
  * the runner agree on the exact string the CLI emits.

package/dist/core/errors.d.ts

@@ -32,4 +32,12 @@ export declare class ProtocolVersionMismatchError extends Error {
     readonly cliProtocolVersion: string;
     readonly sdkProtocolVersion: string;
     constructor(cliProtocolVersion: string, sdkProtocolVersion: string);
+}
+/**
+ * Thrown when an SDK operation requires a protocol capability that the
+ * running qodercli process did not advertise in its system/init message.
+ */
+export declare class UnsupportedCliCapabilityError extends Error {
+    readonly capability: string;
+    constructor(capability: string);
 }

package/dist/core/runtime-launch-options.d.ts

@@ -61,6 +61,7 @@ export interface RuntimeLaunchConfig {
 }
 export declare function isScriptFile(filePath: string): boolean;
 export declare function resolveDefaultCliPath(): string;
+export declare function resolveUserInstalledCliPath(): string | null;
 export declare class RuntimeLaunchOptionsBuilder {
     private readonly options;
     private readonly diagnostics?;

package/dist/core/runtime-selection.d.ts

@@ -0,0 +1,24 @@
+import type { DefaultRuntimeTransport } from './default-runtime.js';
+export interface ImplicitRuntimeOptions {
+    pathToQoderCLIExecutable?: string;
+    executable?: string;
+    executableArgs?: readonly string[];
+    spawnQoderCLIProcess?: unknown;
+}
+export type ImplicitRuntimeSelection = {
+    transport: 'process';
+} | {
+    transport: 'worker';
+    pathToQoderWorkerRuntime?: string;
+};
+/**
+ * Distinguish a Qoder Worker entry from a CLI native binary or script entry.
+ * Unrecognized JavaScript paths remain process CLI entries for compatibility.
+ */
+export declare function isQoderWorkerRuntimePath(candidate: string): boolean;
+/**
+ * Select the local runtime when the caller has not supplied an explicit
+ * transport provider. Explicit paths and process-only launch options override
+ * the transport baked into the SDK package.
+ */
+export declare function resolveImplicitRuntimeSelection(options: ImplicitRuntimeOptions, packageDefault: DefaultRuntimeTransport, environment?: NodeJS.ProcessEnv): ImplicitRuntimeSelection;

package/dist/index.d.ts

@@ -70,7 +70,7 @@ export { listPlugins, enablePlugin, disablePlugin, installPlugin, uninstallPlugi
 export type { PluginDetails, PluginResources, InstallPluginResult, UninstallPluginResult } from './types/plugins.js';
 export { submitFeedback } from './feedback.js';
 export type { SubmitFeedbackParams, SubmitFeedbackOptions, IntegrationMode, } from './feedback.js';
-export { AbortError, ModelPolicyTimeoutError, ProtocolVersionMismatchError, } from './core/errors.js';
+export { AbortError, ModelPolicyTimeoutError, ProtocolVersionMismatchError, UnsupportedCliCapabilityError, } from './core/errors.js';
 export { AuthAccessTokenEnvVarError, AuthServiceAccountEnvVarError, } from './core/runtime-launch-options.js';
 export { WIRE_PROTOCOL_VERSION } from './protocol/version.js';
 export type { ModelPromptPatch, ModelPromptPatches, } from './protocol/model-prompt-patches.js';
@@ -83,7 +83,7 @@ export type { AccessTokenInput, AuthOptions, FetchServiceAccountToken, ServiceAc
  */
 export type { FetchJobToken, JobTokenAuthOptions, JobTokenRequest, JobTokenResult, } from './types/auth.js';
 export type { AccountInfo, UsageAddOnQuotaBucket, UsageInfo, UsageOrgResourcePackage, UsageQuotaBucket, SessionCreditsUsage, ApiKeySource, ExitReason, FastModeState, ConfigScope, SettingSource, SDKAssistantMessageError, SDKStatus, EffortLevel, ThinkingAdaptive, ThinkingEnabled, ThinkingDisabled, ThinkingConfig, ModelInfo, ModelSource, ServerModelJson, ServerModelJsonValue, ModelStrategy, ModelPromotion, LocalizedModelText, ModelContextConfig, ModelContextWindowEntry, ModelEffortEntry, ModelThinkingConfig, ModelThinkingDisabled, ModelThinkingEnabled, ModelUsage, NonNullableUsage, SlashCommand, ToolConfig, SdkPluginConfig, } from './types/common.js';
-export type { SDKMessage, SDKAssistantMessage, SDKUserMessage, SDKUserMessageReplay, SDKResultMessage, SDKResultSuccess, SDKResultError, SDKSystemMessage, SDKSystemInitMessage, SDKSystemMessageSubtype, SDKSystemMessageBySubtype, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKMirrorErrorMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, } from './types/messages.js';
+export type { SDKMessage, SDKAssistantMessage, SDKUserMessage, SDKUserMessageReplay, SDKResultMessage, SDKResultSuccess, SDKResultError, SDKSystemMessage, SDKSystemInitMessage, SDKSystemMessageSubtype, SDKSystemMessageBySubtype, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKMirrorErrorMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, } from './types/messages.js';
 export type { DefaultRuntimeTransport, } from './core/default-runtime.js';
 export type { QueryTransportCreateOptions, QueryTransportProviderOption, } from './core/query-transport.js';
 export type { ProcessTransportOptions } from './core/process-transport.js';
@@ -95,13 +95,13 @@ export type { SettingSource as SettingSourceFromOptions } from './types/options.
 export type { PermissionMode, PermissionBehavior, PermissionDecisionClassification, PermissionUpdateDestination, PermissionRuleValue, PermissionUpdate, PermissionResult, CanUseToolOptions, } from './types/permissions.js';
 export type { HookEvent, HookPermissionDecision, HookCallback, HookCallbackMatcher, HookInput, HookSpecificOutput, HookJSONOutput, AsyncHookJSONOutput, SyncHookJSONOutput, BaseHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, UserPromptSubmitHookInput, SessionStartHookInput, SessionEndHookInput, StopHookInput, SubagentStartHookInput, SubagentStopHookInput, PreCompactHookInput, PostCompactHookInput, PermissionRequestHookInput, InstructionsLoadedHookInput, CwdChangedHookInput, FileChangedHookInput, PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, SessionStartHookSpecificOutput, SubagentStartHookSpecificOutput, PermissionRequestHookSpecificOutput, CwdChangedHookSpecificOutput, FileChangedHookSpecificOutput, } from './types/hooks.js';
 export type { McpStdioServerConfig, McpSSEServerConfig, McpHttpServerConfig, McpSdkServerConfig, McpSdkServerConfigWithInstance, McpServerConfig, McpServerToolPolicy, McpServerConfigForProcessTransport, McpServerStatus, McpServerStatusConfig, } from './types/mcp.js';
-export type { AgentDefinition, AgentInfo, AgentMcpServerSpec, } from './types/agents.js';
-export type { SDKSessionInfo, SessionMessage, ListSessionsOptions, GetSessionInfoOptions, GetSessionMessagesOptions, GetSubagentMessagesOptions, ListSubagentsOptions, SessionMutationOptions, ForkSessionOptions, ForkSessionResult, RewindFilesResult, } from './types/session.js';
+export type { AgentDefinition, AgentInfo, AgentMemoryScope, AgentMcpServerSpec, } from './types/agents.js';
+export type { SDKSessionInfo, SessionMessage, ListSessionsOptions, GetSessionInfoOptions, GetSessionMessagesOptions, GetSubagentMessagesOptions, ListSubagentsOptions, SessionMutationOptions, ForkSessionOptions, ForkSessionResult, RewindFilesResult, RewindScope, RewindStatus, RewindFileFailure, RewindResult, } from './types/session.js';
 export type { Settings, ResolvedSettings, ResolvedSettingsSource, } from './types/settings.js';
 export { filterEscalatingDefaultMode } from './types/settings.js';
 export type { QoderModelPurpose } from './types/control.js';
-export type { SDKControlRequest, SDKControlResponse, SDKControlInterruptResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGetUsageInfoRequest, SDKControlGetUsageInfoResponse, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, } from './types/control.js';
+export type { SDKControlRequest, SDKControlResponse, SDKControlInterruptResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGetUsageInfoRequest, SDKControlGetUsageInfoResponse, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, SDKControlStopTaskRequest, SDKControlBackgroundTasksRequest, SDKControlBackgroundTasksResponse, } from './types/control.js';
 export type { SDKControlGetModelPolicyRequest, SDKControlGetModelPolicyResponse, SDKCapabilities, ModelPolicyContext, ModelPolicyResult, ModelPolicyProvider, } from './types/model-policy-provider.js';
 export type { SDKControlGetByokConfigRequest, SDKControlGetByokConfigResponse, SDKControlValidateByokModelRequest, SDKControlValidateByokModelResponse, BYOKModelValidationInput, BYOKProviderInfo, BYOKModelTypeInfo, BYOKModelInfo, CustomModel, } from './types/byok.js';
-export type { AgentInput, AgentOutput, BashInput, FileReadInput, FileReadOutput, FileEditInput, FileWriteInput, GlobInput, GrepInput, WebFetchInput, WebSearchInput, AskUserQuestionInput, NotebookEditInput, ExitPlanModeInput, TodoWriteInput, ToolInputSchemas, ToolOutputSchemas, } from './types/tools.js';
+export type { AgentInput, AgentOutput, AgentToolCompletionResult, AgentToolBackgroundLaunchResult, AgentToolTeammateSpawnedResult, BashInput, FileReadInput, FileReadOutput, FileEditInput, FileWriteInput, GlobInput, GrepInput, WebFetchInput, WebSearchInput, AskUserQuestionInput, NotebookEditInput, TaskCreateInput, TaskCreateOutput, TaskGetInput, TaskGetOutput, TaskUpdateInput, TaskUpdateOutput, TaskListInput, TaskListOutput, ExitPlanModeInput, TodoWriteInput, ToolInputSchemas, ToolOutputSchemas, } from './types/tools.js';
 export type { FeedbackResult } from './types/account.js';