@qoder-ai/qoder-agent-sdk 1.0.25 → 1.0.27

package/dist/types/options.d.ts

@@ -18,7 +18,8 @@ import type { PluginDetails } from './plugins.js';
 import type { SessionStore, SessionStoreFlush } from '../session/session-store.js';
 import type { ModelPromptPatches } from '../protocol/model-prompt-patches.js';
 import type { MemoryOptions } from './memory.js';
-import type { SDKGoalSnapshot, SDKGoalStatus } from '../protocol/control.js';
+import type { EvolutionOptions } from './skill-evolution.js';
+import type { SDKGoalSnapshot, SDKGoalStatus, SDKPlanModeSnapshot } from '../protocol/control.js';
 export type { CanUseTool };
 export type { AuthOptions };
 export type ElicitationRequest = {
@@ -147,12 +148,15 @@ export type Options = {
     skills?: string[] | 'all';
     extensions?: string[];
     /**
-     * Proxy URL used by the qodercli child process for outbound network traffic.
+     * Proxy URL used by qodercli for its own outbound network traffic.
      *
      * Supports the same schemes as qodercli: `http://`, `https://`,
-     * `socks5://`, and `socks://`. When set, the SDK writes this value to
-     * `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY`, and `http_proxy` in the child
-     * environment.
+     * `socks5://`, and `socks://`. The SDK passes this value through qodercli's
+     * startup interface without rewriting proxy environment variables.
+     *
+     * When omitted, SDK-integrated qodercli connects directly and does not
+     * discover a proxy from the inherited environment. Environment variables are
+     * still preserved for tools and subprocesses launched by the agent.
      */
     proxy?: string;
     /**
@@ -176,6 +180,7 @@ export type Options = {
     };
     executable?: 'bun' | 'deno' | 'node';
     executableArgs?: string[];
+    /** Additional qodercli flags. `proxy` is reserved; use `proxy` instead. */
     extraArgs?: Record<string, string | null>;
     enableFileCheckpointing?: boolean;
     toolConfig?: ToolConfig;
@@ -205,6 +210,8 @@ export type Options = {
      * Functions stay in the SDK process and are bridged through control requests.
      */
     memory?: MemoryOptions;
+    /** Configure component evolution capabilities for this query. */
+    evolution?: EvolutionOptions;
     onElicitation?: OnElicitation;
     /**
      * Called when the SDK detects that authentication has expired or
@@ -245,6 +252,13 @@ export type Options = {
      */
     pathToQoderCLIExecutable?: string;
     permissionMode?: PermissionMode;
+    /**
+     * Initial Plan Mode state for the main session. Applied after the CLI
+     * initialize handshake and before the first user message, without changing
+     * the underlying `permissionMode`. Requires the CLI `plan_mode_v1`
+     * capability.
+     */
+    planMode?: boolean;
     allowDangerouslySkipPermissions?: boolean;
     /**
      * MCP tool name to use for permission prompts. Mutually exclusive with
@@ -403,6 +417,14 @@ export interface Query extends AsyncGenerator<SDKMessage, void> {
     getGoal?(): Promise<SDKGoalSnapshot | null>;
     /** Clear the session goal; returns whether a goal was cleared. */
     clearGoal?(): Promise<boolean>;
+    /**
+     * Enter or leave the main session's independent Plan Mode. The current tool
+     * permission mode is preserved. Requires the CLI `plan_mode_v1` capability.
+     * Only present on the local CLI transport; absent on cloud-agent queries.
+     */
+    setPlanMode?(active: boolean): Promise<SDKPlanModeSnapshot>;
+    /** Read the authoritative Plan Mode state from the running CLI session. */
+    getPlanMode?(): Promise<SDKPlanModeSnapshot>;
     setPermissionMode(mode: PermissionMode): Promise<void>;
     setModel(model?: string): Promise<void>;
     /**
@@ -489,6 +511,8 @@ export interface Query extends AsyncGenerator<SDKMessage, void> {
     seedReadState(path: string, mtime: number): Promise<void>;
     /** Wait until pending TurnComplete memory generation has finished. */
     flushMemory(): Promise<void>;
+    /** Wait until pending TurnComplete skill evolution review has finished. */
+    flushSkillEvolution(): Promise<void>;
     /** Reload configured memory consumption files without changing config. */
     refreshMemory(): Promise<void>;
     /**

package/dist/types/session.d.ts

@@ -89,10 +89,18 @@ export type ListSessionsOptions = SessionStoreOptions & {
 export type GetSessionInfoOptions = SessionStoreOptions & {
     dir?: string;
 };
+/** Message projection returned by {@link getSessionMessages}. */
+export type SessionMessageView = 'runtime' | 'historical';
 export type GetSessionMessagesOptions = SessionStoreOptions & {
     dir?: string;
     limit?: number;
     offset?: number;
+    /**
+     * `runtime` returns the latest compact summary and post-compact messages.
+     * `historical` returns real messages across compact boundaries while hiding
+     * compact boundary and summary implementation records. Defaults to `runtime`.
+     */
+    view?: SessionMessageView;
     /**
      * Include `system` entries in the result (compact boundaries, informational
      * notices). Defaults to false — only user/assistant are returned.

package/dist/types/skill-evolution.d.ts

@@ -0,0 +1,41 @@
+import type { SkillEvolutionGateInput, SkillEvolutionGateResult, SkillEvolutionResult, SerializableSkillEvolutionConfig } from '../protocol/skill-evolution.js';
+export type { SkillEvolutionMode } from '../protocol/skill-evolution.js';
+export declare const MAX_SKILL_EVOLUTION_REVIEW_THRESHOLD = 10;
+export type { EffectiveEvolutionConfig, EffectiveSkillEvolutionConfig, SkillEvolutionGateInput, SkillEvolutionGateResult, SkillEvolutionResult, SerializableEvolutionConfig, SerializableSkillEvolutionConfig, SkillEvolutionSuggestion, } from '../protocol/skill-evolution.js';
+export type SkillEvolutionShouldReview = (input: SkillEvolutionGateInput, options: {
+    signal: AbortSignal;
+}) => Promise<SkillEvolutionGateResult>;
+export type SkillEvolutionGenerationOptions = {
+    enabled?: boolean;
+    prompt?: string;
+    maxSuggestions?: number;
+    turnComplete?: {
+        enabled?: boolean;
+        /** Integer from 1 to 10. Defaults to 5. */
+        reviewThreshold?: number;
+        shouldReview?: SkillEvolutionShouldReview;
+        timeoutMs?: number;
+        onGateError?: 'skip' | 'report_failed';
+    };
+    onResult?: (result: SkillEvolutionResult) => void | Promise<void>;
+};
+export type SkillEvolutionOptions = {
+    mode: 'native';
+    generation?: Pick<SkillEvolutionGenerationOptions, 'enabled' | 'onResult'> & {
+        turnComplete?: Pick<NonNullable<SkillEvolutionGenerationOptions['turnComplete']>, 'reviewThreshold'>;
+    };
+} | {
+    mode: 'custom';
+    generation?: SkillEvolutionGenerationOptions;
+};
+export type EvolutionOptions = {
+    skill?: SkillEvolutionOptions;
+};
+export type SkillEvolutionRuntimeCallbacks = {
+    shouldReviewCallbacks: ReadonlyMap<string, SkillEvolutionShouldReview>;
+    onResult?: SkillEvolutionGenerationOptions['onResult'];
+};
+export type PreparedSkillEvolutionOptions = {
+    config?: SerializableSkillEvolutionConfig;
+    callbacks?: SkillEvolutionRuntimeCallbacks;
+};

package/dist/types/tools.d.ts

@@ -26,6 +26,7 @@ export type AgentToolCompletionResult = {
     outputPath?: string;
     transcriptPath?: string;
     worktreePath?: string;
+    worktreeBranch?: string;
     remoteContextId?: string;
     remoteTaskId?: string;
 };
@@ -324,23 +325,40 @@ export type ConfigOutput = {
     error?: string;
 };
 export type EnterWorktreeInput = {
+    /** Create (or resume) a managed worktree with this name. */
     name?: string;
+    /** Enter an existing registered Git worktree instead of creating one. */
+    path?: string;
 };
+/**
+ * Successful EnterWorktree result. Failures use ToolResultBlock.is_error/content.
+ *
+ * SDK 1.0.25 and earlier declared a snake_case success/error object that was
+ * never the qodercli wire shape. This type intentionally follows the actual
+ * structured result available with the paired qodercli 1.1.27 or newer.
+ */
 export type EnterWorktreeOutput = {
-    worktree_path: string;
-    branch_name: string;
-    success: boolean;
-    error?: string;
+    worktreePath: string;
+    worktreeBranch?: string;
+    message: string;
 };
 export type ExitWorktreeInput = {
     action: 'keep' | 'remove';
     discard_changes?: boolean;
 };
+/** Successful ExitWorktree result. Failures use ToolResultBlock.is_error/content. */
 export type ExitWorktreeOutput = {
-    success: boolean;
-    error?: string;
-    uncommitted_files?: string[];
-    unmerged_commits?: string[];
+    action: 'keep' | 'remove';
+    originalCwd: string;
+    worktreePath: string;
+    worktreeBranch?: string;
+    /** Reserved for forward compatibility; current qodercli does not populate it. */
+    tmuxSessionName?: string;
+    /** Reserved for forward compatibility; current qodercli does not populate it. */
+    discardedFiles?: number;
+    /** Reserved for forward compatibility; current qodercli does not populate it. */
+    discardedCommits?: number;
+    message: string;
 };
 export type TodoWriteInput = {
     todos: Array<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoder-ai/qoder-agent-sdk",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "TypeScript SDK for building Qoder-powered coding agents.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,7 @@
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
   },
-  "qoderCliVersion": "1.1.26",
+  "qoderCliVersion": "1.1.31",
   "qoderSdkBrand": "global",
   "license": "SEE LICENSE IN LICENSE"
 }

package/scripts/postinstall.cjs

@@ -9,7 +9,6 @@
  * - QODER_CLI_MIRROR: CDN base URL. Accepts .../qodercli, .../qodercli/dev, or .../releases
  * - QODER_WORKER_RUNTIME_URL: explicit worker runtime tgz URL override
  * - QODER_CLI_VERSION: override package.json qoderCliVersion
- * - QODER_CLI_SITE: download site. Supports global and cn
  * - QODER_CLI_PLATFORM: override target artifact, e.g. darwin-arm64, linux-x64-musl
  * - QODER_SKIP_CHECKSUM=1|true: skip .sha256 verification
  */
@@ -30,6 +29,18 @@ const CN_DEV_DOWNLOAD_BASE_URL = 'https://static.qoder.com.cn/qoder-cli-cn/dev/r
 const PACKAGE_JSON = require('../package.json');
 const LOG_PREFIX = `[${PACKAGE_JSON.name ?? '@qoder-ai/qoder-agent-sdk'}]`;
 const WORKER_RUNTIME_ENTRY_NAMES = ['qoder-worker-runtime.obf.mjs', 'qoder-worker-runtime.mjs'];
+const SUPPORTED_CLI_PLATFORM_TARGETS = Object.freeze([
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-arm64-musl',
+  'linux-x64',
+  'linux-x64-baseline',
+  'linux-x64-musl',
+  'openharmony-arm64',
+  'windows-arm64',
+  'windows-x64',
+]);
 
 function isTruthy(value) {
   return value === '1' || value === 'true';
@@ -61,11 +72,11 @@ function normalizeCliSite(value) {
   const normalized = String(value).trim().toLowerCase();
   if (normalized === 'global') return 'global';
   if (normalized === 'cn') return 'cn';
-  throw new Error(`Unsupported QODER_CLI_SITE "${value}". Supported: global, cn`);
+  throw new Error(`Unsupported package.json qoderSdkBrand "${value}". Supported: global, cn`);
 }
 
 function getCliSite() {
-  return normalizeCliSite(process.env.QODER_CLI_SITE ?? PACKAGE_JSON.qoderSdkBrand ?? 'global');
+  return normalizeCliSite(PACKAGE_JSON.qoderSdkBrand ?? 'global');
 }
 
 function getCliArtifactPrefix(site = getCliSite()) {
@@ -86,11 +97,10 @@ function getDownloadBaseUrl(version = getCliVersion()) {
   return GLOBAL_PROD_DOWNLOAD_BASE_URL;
 }
 
-function getWorkerRuntimeDownloadBaseUrl(version = getCliVersion()) {
+function getWorkerRuntimeDownloadBaseUrl(version = getCliVersion(), site = getCliSite()) {
   if (process.env.QODER_CLI_MIRROR) {
     return process.env.QODER_CLI_MIRROR;
   }
-  const site = getCliSite();
   if (site === 'cn') {
     return isDevCliVersion(version) ? CN_DEV_DOWNLOAD_BASE_URL : CN_PROD_DOWNLOAD_BASE_URL;
   }
@@ -134,22 +144,9 @@ function linuxX64HasAvx2() {
 
 function normalizePlatformOverride(value) {
   const normalized = value.replace(/_/g, '-').replace(/-amd64(?=-|$)/, '-x64');
-  const supported = new Set([
-    'darwin-arm64',
-    'darwin-x64',
-    'linux-arm64',
-    'linux-arm64-musl',
-    'linux-x64',
-    'linux-x64-baseline',
-    'linux-x64-musl',
-    'openharmony-arm64',
-    'windows-arm64',
-    'windows-x64',
-  ]);
-
-  if (!supported.has(normalized)) {
+  if (!SUPPORTED_CLI_PLATFORM_TARGETS.includes(normalized)) {
     throw new Error(
-      `Unsupported QODER_CLI_PLATFORM "${value}". Supported: ${[...supported].join(', ')}`,
+      `Unsupported QODER_CLI_PLATFORM "${value}". Supported: ${SUPPORTED_CLI_PLATFORM_TARGETS.join(', ')}`,
     );
   }
   return normalized;
@@ -213,11 +210,19 @@ function getWorkerRuntimeTarget(target = getPlatformTarget()) {
   if (platform === 'darwin') return `darwin-${arch}`;
   if (platform === 'linux') return `linux-${arch}`;
   if (platform === 'windows') return `win32-${arch}`;
+  if (platform === 'openharmony') return `openharmony-${arch}`;
   throw new Error(
-    `Worker runtime platform artifacts do not support ${target}. Supported: darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-arm64, windows-x64`,
+    `Worker runtime platform artifacts do not support ${target}. Supported: darwin-arm64, darwin-x64, linux-arm64, linux-x64, openharmony-arm64, windows-arm64, windows-x64`,
   );
 }
 
+function getWorkerRuntimeArtifactTargets() {
+  return [
+    'universal',
+    ...new Set(SUPPORTED_CLI_PLATFORM_TARGETS.map((target) => getWorkerRuntimeTarget(target))),
+  ];
+}
+
 function getWorkerRuntimeArtifactName(site = getCliSite(), target = getPlatformTarget()) {
   const workerTarget = getWorkerRuntimeTarget(target);
   return `${getCliArtifactPrefix(site)}-worker-runtime-${workerTarget}.tgz`;
@@ -230,6 +235,10 @@ function getWorkerRuntimeArtifactNameTemplate(site = getCliSite()) {
 function getWorkerRuntimeRequiredAssets(target = getPlatformTarget()) {
   const workerTarget = getWorkerRuntimeTarget(target);
   const [platform, arch] = workerTarget.split('-');
+  // ripgrep has no HarmonyOS build, so its worker archive ships without one and
+  // search falls back to a system rg. Demanding the asset would make every
+  // HarmonyOS install fail the completeness check.
+  if (platform === 'openharmony') return [];
   return [
     path.join(
       'vendor',
@@ -240,10 +249,6 @@ function getWorkerRuntimeRequiredAssets(target = getPlatformTarget()) {
   ];
 }
 
-function hasWorkerRuntimeDownloadSiteOverride() {
-  return Boolean(process.env.QODER_CLI_SITE || process.env.QODER_CLI_MIRROR);
-}
-
 function getManifestWorkerRuntime(manifest = readRuntimeManifest()) {
   const workerRuntime = manifest?.workerRuntime;
   return workerRuntime && typeof workerRuntime === 'object' ? workerRuntime : null;
@@ -281,14 +286,17 @@ function getManifestWorkerRuntimeSha256(manifest = readRuntimeManifest()) {
   return checksum ? checksum.trim().toLowerCase() : null;
 }
 
-function getWorkerRuntimeDownloadUrlTemplate() {
+function getWorkerRuntimeDownloadUrlTemplate(site = getCliSite()) {
   const version = getCliVersion();
-  const baseUrl = normalizeDownloadBaseUrl(getWorkerRuntimeDownloadBaseUrl(version), version);
-  return `${baseUrl}/${getWorkerRuntimeArtifactNameTemplate()}`;
+  const baseUrl = normalizeDownloadBaseUrl(
+    getWorkerRuntimeDownloadBaseUrl(version, site),
+    version,
+  );
+  return `${baseUrl}/${getWorkerRuntimeArtifactNameTemplate(site)}`;
 }
 
-function getWorkerRuntimeDefaultDownloadUrl() {
-  return getWorkerRuntimeDownloadUrlTemplate().replace(
+function getWorkerRuntimeDefaultDownloadUrl(site = getCliSite()) {
+  return getWorkerRuntimeDownloadUrlTemplate(site).replace(
     '{target}',
     getWorkerRuntimeTarget(),
   );
@@ -299,7 +307,7 @@ function getWorkerRuntimeDownloadUrl() {
     return process.env.QODER_WORKER_RUNTIME_URL;
   }
 
-  if (!hasWorkerRuntimeDownloadSiteOverride()) {
+  if (!process.env.QODER_CLI_MIRROR) {
     const template = getManifestWorkerRuntimeDownloadUrlTemplate();
     if (template) {
       return template.replace('{target}', getWorkerRuntimeTarget());
@@ -781,7 +789,7 @@ function assertWorkerRuntimeComplete(runtimeDir, sourceDescription) {
   return runtimePath;
 }
 
-function assertWorkerRuntimeIdentity(runtimeDir) {
+function assertWorkerRuntimeIdentity(runtimeDir, brand = getCliSite()) {
   const runtimeInfoPath = path.join(runtimeDir, 'runtime-info.json');
   if (!fs.existsSync(runtimeInfoPath)) {
     throw new Error(`Downloaded Worker runtime is missing identity metadata: ${runtimeInfoPath}`);
@@ -795,8 +803,7 @@ function assertWorkerRuntimeIdentity(runtimeDir) {
   }
 
   const expectedTarget = getWorkerRuntimeTarget();
-  const expectedSite = getCliSite();
-  const expectedProductName = getCliArtifactPrefix(expectedSite);
+  const expectedProductName = getCliArtifactPrefix(brand);
   const expectedVersion = getCliVersion();
   const mismatches = [];
 
@@ -809,8 +816,8 @@ function assertWorkerRuntimeIdentity(runtimeDir) {
   if (runtimeInfo.version !== expectedVersion) {
     mismatches.push(`version=${String(runtimeInfo.version)} (expected ${expectedVersion})`);
   }
-  if (runtimeInfo.build?.site !== expectedSite) {
-    mismatches.push(`site=${String(runtimeInfo.build?.site)} (expected ${expectedSite})`);
+  if (runtimeInfo.build?.site !== brand) {
+    mismatches.push(`site=${String(runtimeInfo.build?.site)} (expected ${brand})`);
   }
   if (runtimeInfo.build?.productName !== expectedProductName) {
     mismatches.push(
@@ -832,7 +839,7 @@ function installExtractedWorkerRuntime(extractDir, workerDir, options = {}) {
   }
   assertWorkerRuntimeComplete(contentRoot, contentRoot);
   if (options.validateIdentity === true) {
-    assertWorkerRuntimeIdentity(contentRoot);
+    assertWorkerRuntimeIdentity(contentRoot, options.brand);
   }
 
   fs.rmSync(workerDir, { recursive: true, force: true });
@@ -846,8 +853,12 @@ function installExtractedWorkerRuntime(extractDir, workerDir, options = {}) {
 }
 
 async function downloadAndInstallWorkerRuntime(workerDir, options = {}) {
-  const url = options.urlOverride ?? getWorkerRuntimeDownloadUrl();
-  const expectedSha256 = options.urlOverride ? null : getWorkerRuntimeExpectedSha256(url);
+  const brand = options.brand ?? getCliSite();
+  const url =
+    options.urlOverride ??
+    (options.brand ? getWorkerRuntimeDefaultDownloadUrl(brand) : getWorkerRuntimeDownloadUrl());
+  const expectedSha256 =
+    options.urlOverride || options.brand ? null : getWorkerRuntimeExpectedSha256(url);
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'qoder-worker-runtime-'));
   const archivePath = path.join(tempDir, path.basename(new URL(url).pathname));
   const extractDir = path.join(tempDir, 'extract');
@@ -860,6 +871,7 @@ async function downloadAndInstallWorkerRuntime(workerDir, options = {}) {
     return {
       runtimePath: installExtractedWorkerRuntime(extractDir, workerDir, {
         validateIdentity: true,
+        brand,
       }),
       url,
     };
@@ -986,6 +998,7 @@ module.exports = {
   getWorkerRuntimeExpectedSha256,
   getWorkerRuntimeArtifactName,
   getWorkerRuntimeArtifactNameTemplate,
+  getWorkerRuntimeArtifactTargets,
   getWorkerRuntimeDownloadBaseUrl,
   getWorkerRuntimeDownloadUrl,
   getWorkerRuntimeDownloadUrlTemplate,