@qoder-ai/qoder-agent-sdk 1.0.16 → 1.0.19

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,61 +78,73 @@ 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.
 
-To reuse the local `qodercli` login state:
+| Authentication method | Identity | Use case |
+| --- | --- | --- |
+| Personal Access Token (PAT) | A Qoder user | Automation that needs the user's permissions and data |
+| Service Account | An organization workload | Services and jobs that should not depend on a personal account |
+| Local `qodercli` session | The signed-in user | Interactive development on a workstation |
+
+For a PAT, generate a token at
+[qoder.com/account/integrations](https://qoder.com/account/integrations), store
+it in a secret manager, and expose it through the default environment variable:
+
+```bash
+export QODER_PERSONAL_ACCESS_TOKEN=your-token
+```
 
 ```ts
-import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
+import { accessTokenFromEnv, query } from "@qoder-ai/qoder-agent-sdk";
 
 const q = query({
   prompt: "Summarize this repository.",
   options: {
-    auth: qodercliAuth(),
+    auth: accessTokenFromEnv(),
     cwd: process.cwd(),
   },
 });
 ```
 
-To authenticate with a personal access token:
-
-Generate a Personal Access Token at
-[qoder.com/account/integrations](https://qoder.com/account/integrations):
-
-1. Sign in to your Qoder account.
-2. Open the integrations page.
-3. Create a new PAT, choosing the expiry and scopes you need.
-4. Copy the token immediately. The value cannot be retrieved again after the
-   page is closed.
-
-Use separate tokens for local scripts, CI, and production services when
-possible, so each environment can be revoked independently. Do not hard-code
-tokens in source code.
-
-```bash
-export QODER_PERSONAL_ACCESS_TOKEN=your-token
-```
+For a Service Account, read the key from your secret manager and pass it
+directly to the SDK:
 
 ```ts
-import { accessTokenFromEnv, query } from "@qoder-ai/qoder-agent-sdk";
+import { query, serviceAccount } from "@qoder-ai/qoder-agent-sdk";
+
+// Get the Service Account key from the host's secret manager adapter.
+const serviceAccountKey = await readSecret("qoder-service-account-key");
 
 const q = query({
   prompt: "Summarize this repository.",
   options: {
-    auth: accessTokenFromEnv(),
+    auth: serviceAccount({ serviceAccountKey }),
     cwd: process.cwd(),
   },
 });
 ```
 
-`accessTokenFromEnv()` reads `QODER_PERSONAL_ACCESS_TOKEN` by default.
+The SDK and CLI obtain and refresh short-lived Service Account tokens for this
+authentication method. A host can retain the Service Account key and use
+`serviceAccount({ fetchServiceAccountToken })` to obtain and refresh
+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
+complete setup instructions and security guidance.
 
 ## Quick Start
 

package/dist/auth.d.ts

@@ -1,6 +1,9 @@
-import type { AuthOptions, FetchJobToken, JobTokenAuthOptions } from './types/auth.js';
-export declare const DEFAULT_ACCESS_TOKEN_ENV_VAR = "QODER_PERSONAL_ACCESS_TOKEN";
+import type { AuthOptions, FetchJobToken, JobTokenAuthOptions, ServiceAccountAuthOptions, ServiceAccountCredentials } from './types/auth.js';
+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;
+export declare function serviceAccount(credentials: ServiceAccountCredentials): ServiceAccountAuthOptions;
+export declare function serviceAccountFromEnv(envVar?: string): ServiceAccountAuthOptions;
 export declare function jobToken(fetchJobToken: FetchJobToken): JobTokenAuthOptions;

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.
  *
@@ -33,16 +30,29 @@ export declare const SDK_VERSION = "1.0.16";
  * to resolve them via the `canUseTool` callback.
  */
 export declare const PERMISSION_PROMPT_TOOL_STDIO = "stdio";
+/**
+ * Exit code the Qoder CLI emits for `FATAL_AUTHENTICATION_ERROR`.
+ * See qodercli-next packages/core/src/utils/exitCodes.ts.
+ */
+export declare const CLI_EXIT_CODE_AUTH_ERROR = 41;
 /**
  * Built-in qodercli tools exposed by SDK sessions when callers do not pass
  * `options.tools`.
  *
  * 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/runtime-launch-options.d.ts

@@ -9,6 +9,10 @@ export declare class AuthAccessTokenEnvVarError extends Error {
     readonly code: "auth_access_token_env_var_not_configured";
     constructor(envVar: string);
 }
+export declare class AuthServiceAccountEnvVarError extends Error {
+    readonly code: "auth_service_account_env_var_not_configured";
+    constructor(envVar: string);
+}
 type ToolsOption = string[] | {
     type: 'preset';
     preset: 'qodercli';
@@ -57,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?;
@@ -68,6 +73,7 @@ export declare class RuntimeLaunchOptionsBuilder {
     cleanupGeneratedSettings(): void;
     cleanupAuthPayload(): Promise<void>;
     buildEnv(): Record<string, string>;
+    private serviceAccountCredentialEnvVars;
     buildArgs(): string[];
     private buildSettingsArg;
     private applyFileCheckpointingSetting;
@@ -82,6 +88,7 @@ export declare class RuntimeLaunchOptionsBuilder {
     private writeGeneratedSettingsFile;
     private createAuthPayloadFile;
     private buildAuthPayload;
+    private resolveServiceAccountKey;
     private resolveAccessToken;
 }
 export {};

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

@@ -55,7 +55,7 @@ export { query } from './query/query.js';
 export { DEFAULT_RUNTIME_TRANSPORT, } from './core/default-runtime.js';
 export { ProcessTransport, QoderCliProcessError, } from './core/process-transport.js';
 export { hasResolvableQoderWorkerRuntime, QoderWorkerRuntimeError, WorkerTransport, resolveQoderWorkerRuntimePath, } from './core/worker-transport.js';
-export { DEFAULT_ACCESS_TOKEN_ENV_VAR, accessToken, accessTokenFromEnv, jobToken, qodercliAuth, } from './auth.js';
+export { DEFAULT_ACCESS_TOKEN_ENV_VAR, DEFAULT_SERVICE_ACCOUNT_ENV_VAR, accessToken, accessTokenFromEnv, jobToken, qodercliAuth, serviceAccount, serviceAccountFromEnv, } from './auth.js';
 export { createSdkMcpServer, tool } from './mcp/sdk-mcp-server.js';
 export type { AnyZodRawShape, InferShape, SdkMcpToolDefinition, ToolExtras, CreateSdkMcpServerOptions, } from './mcp/sdk-mcp-server.js';
 export type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
@@ -71,17 +71,18 @@ export type { PluginDetails, PluginResources, InstallPluginResult, UninstallPlug
 export { submitFeedback } from './feedback.js';
 export type { SubmitFeedbackParams, SubmitFeedbackOptions, IntegrationMode, } from './feedback.js';
 export { AbortError, ModelPolicyTimeoutError, ProtocolVersionMismatchError, } 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';
 export { HOOK_EVENTS, EXIT_REASONS } from './core/constants.js';
 import * as coreTypes from './types/index.js';
 export { coreTypes };
-export type { AccessTokenInput, AuthOptions } from './types/auth.js';
+export type { AccessTokenInput, AuthOptions, FetchServiceAccountToken, ServiceAccountAuthOptions, ServiceAccountCredentials, ServiceAccountKeyInput, ServiceAccountTokenResult, } from './types/auth.js';
 /**
  * @internal Internal auth types for first-party host integration, not general public use.
  */
 export type { FetchJobToken, JobTokenAuthOptions, JobTokenRequest, JobTokenResult, } from './types/auth.js';
-export type { AccountInfo, UsageAddOnQuotaBucket, UsageInfo, UsageOrgResourcePackage, UsageQuotaBucket, 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 { 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 { DefaultRuntimeTransport, } from './core/default-runtime.js';
 export type { QueryTransportCreateOptions, QueryTransportProviderOption, } from './core/query-transport.js';
@@ -102,5 +103,5 @@ export type { QoderModelPurpose } from './types/control.js';
 export type { SDKControlRequest, SDKControlResponse, SDKControlInterruptResponse, SDKControlInitializeResponse, SDKControlGetContextUsageResponse, SDKControlGetUsageInfoRequest, SDKControlGetUsageInfoResponse, SDKControlAddDirectoriesResponse, SDKControlReloadPluginsResponse, } 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, 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';