@qoder-ai/qoder-agent-sdk 1.0.21 → 1.0.23

package/dist/protocol/control.d.ts

@@ -231,6 +231,16 @@ export type SDKControlGetModelPolicyResponse = {
      * the supplied API key instead of the default upstream.
      */
     custom_model?: CustomModel;
+    /**
+     * Optional routing scene label the CLI forwards as the inference request
+     * body `task_id`.
+     */
+    task_id?: string;
+    /**
+     * Optional business sub-task label the CLI forwards as `business.sub_task`
+     * on the inference request (billing/analytics).
+     */
+    sub_task?: string;
 };
 export type SDKControlSetMaxThinkingTokensRequest = {
     type: 'set_max_thinking_tokens';
@@ -514,93 +524,48 @@ export type SDKControlInitializeResponse = {
     capabilities?: string[];
 };
 export type SDKControlGetContextUsageResponse = {
+    model: string;
+    contextWindow: {
+        /** Context occupancy as a percentage from 0 to 100. */
+        usedPercentage: number;
+    };
+    /** Local estimates in the same order and category model as `/context`. */
     categories: Array<{
-        name: string;
-        tokens: number;
-        color: string;
-        isDeferred?: boolean;
-    }>;
-    totalTokens: number;
-    maxTokens: number;
-    rawMaxTokens: number;
-    percentage: number;
-    gridRows: Array<Array<{
-        color: string;
-        isFilled: boolean;
-        categoryName: string;
-        tokens: number;
+        type: 'system_prompt' | 'system_tools' | 'skills' | 'messages' | 'other' | 'free_space' | 'auto_compact';
         percentage: number;
-        squareFullness: number;
-    }>>;
-    model: string;
-    memoryFiles: Array<{
-        path: string;
-        type: string;
-        tokens: number;
-    }>;
-    mcpTools: Array<{
-        name: string;
-        serverName: string;
-        tokens: number;
-        isLoaded?: boolean;
     }>;
-    deferredBuiltinTools?: Array<{
-        name: string;
-        tokens: number;
-        isLoaded: boolean;
-    }>;
-    systemTools?: Array<{
-        name: string;
-        tokens: number;
-    }>;
-    systemPromptSections?: Array<{
-        name: string;
-        tokens: number;
-    }>;
-    agents: Array<{
-        agentType: string;
-        source: string;
-        tokens: number;
-    }>;
-    slashCommands?: {
-        totalCommands: number;
-        includedCommands: number;
-        tokens: number;
+    autoCompact: {
+        enabled: boolean;
+        thresholdPercentage: number;
     };
-    skills?: {
-        totalSkills: number;
-        includedSkills: number;
-        tokens: number;
-        skillFrontmatter: Array<{
+    skills: {
+        count: number;
+        /** Aggregate skill frontmatter as a percentage of the full context. */
+        percentageOfContext: number;
+        items: Array<{
             name: string;
-            source: string;
-            tokens: number;
+            source: 'project' | 'user' | 'built-in' | 'plugin';
+            /** This skill's frontmatter as a percentage of the full context. */
+            percentageOfContext: number;
         }>;
     };
-    autoCompactThreshold?: number;
-    isAutoCompactEnabled: boolean;
-    messageBreakdown?: {
-        toolCallTokens: number;
-        toolResultTokens: number;
-        attachmentTokens: number;
-        assistantMessageTokens: number;
-        userMessageTokens: number;
-        toolCallsByType: Array<{
-            name: string;
-            callTokens: number;
-            resultTokens: number;
-        }>;
-        attachmentsByType: Array<{
-            name: string;
-            tokens: number;
-        }>;
+    duplicateFileReads: Array<{
+        path: string;
+        count: number;
+    }>;
+    session: {
+        messageCount: number;
+        promptCount: number;
+        toolCalls: {
+            total: number;
+            succeeded: number;
+            failed: number;
+        };
+        linesChanged: {
+            added: number;
+            removed: number;
+        };
     };
-    apiUsage: {
-        input_tokens: number;
-        output_tokens: number;
-        cache_creation_input_tokens: number;
-        cache_read_input_tokens: number;
-    } | null;
 };
 export type SDKControlReloadPluginsResponse = {
     commands: SlashCommand[];

package/dist/protocol/index.d.ts

@@ -19,7 +19,7 @@ export type { AICodeTrackingLaunchOptions, QoderAgentLaunchOptions, QoderCliFlag
 export { buildQoderCliFlagSettings, buildQoderCliFlagSettingsArgs, } from './launch.js';
 export type { PermissionMode, PermissionBehavior, PermissionDecisionClassification, PermissionUpdateDestination, PermissionRuleValue, PermissionUpdate, PermissionResult, } from './permissions.js';
 export type { McpStdioServerConfig, McpSSEServerConfig, McpHttpServerConfig, McpSdkServerConfig, McpServerConfigForProcessTransport, McpServerStatus, McpServerStatusConfig, McpSetServersResult, OAuthToken, } from './mcp.js';
-export type { SDKAssistantMessage, SDKUserMessage, SDKUserMessageReplay, SDKResultSuccess, SDKResultError, SDKResultMessage, SDKFileAttachment, SDKSystemMessage, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, SDKPermissionDeniedMessage, SDKPermissionDeniedReasonType, SDKMessage, } from './messages.js';
+export type { SDKAssistantMessage, SDKToolNonExecutionKind, SDKToolResultMeta, SDKUserMessage, SDKUserMessageReplay, SDKResultSuccess, SDKResultError, SDKResultMessage, SDKFileAttachment, SDKSystemMessage, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKStatusMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, SDKPermissionDeniedMessage, SDKPermissionDeniedReasonType, SDKMessage, } from './messages.js';
 export type { BaseHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, UserPromptSubmitHookInput, SessionStartHookInput, SessionEndHookInput, StopHookInput, StopFailureHookInput, SubagentStartHookInput, SubagentStopHookInput, PreCompactHookInput, PostCompactHookInput, PermissionRequestHookInput, PermissionDeniedHookInput, SetupHookInput, TeammateIdleHookInput, TaskCreatedHookInput, TaskCompletedHookInput, ElicitationHookInput, ElicitationResultHookInput, ConfigChangeHookInput, WorktreeCreateHookInput, WorktreeRemoveHookInput, InstructionsLoadedHookInput, CwdChangedHookInput, FileChangedHookInput, HookInput, PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, SessionStartHookSpecificOutput, SetupHookSpecificOutput, SubagentStartHookSpecificOutput, PermissionRequestHookSpecificOutput, ElicitationHookSpecificOutput, ElicitationResultHookSpecificOutput, CwdChangedHookSpecificOutput, FileChangedHookSpecificOutput, WorktreeCreateHookSpecificOutput, SyncHookJSONOutput, AsyncHookJSONOutput, HookJSONOutput, HookEvent, } from './hooks.js';
 export type { AgentMcpServerSpec, AgentDefinition, AgentInfo, AgentMemoryScope, } from './agents.js';
 export { QoderModelPurpose } from './control.js';

package/dist/protocol/index.js

@@ -1 +1 @@
-var r="1.2.0";function i(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function n(e={}){let t={...e.settings??{}},o=e.aiCodeTracking?.installGitCommitHook;if(o!==void 0){let s=t.aiCodeTracking;t.aiCodeTracking={...i(s)?s:{},installGitCommitHook:o}}return t}function l(e={}){let t=n(e);return Object.keys(t).length===0?[]:["--settings",JSON.stringify(t)]}var p={Main:"main",Plan:"plan",Task:"task",Compact:"compact",Title:"title",Suggestion:"suggestion",Generate:"generate",HookPrompt:"hook_prompt",Subagent:"subagent",WebFetch:"web_fetch",ImageGen:"image_gen",Compression:"compression",Utility:"utility"};export{p as QoderModelPurpose,r as WIRE_PROTOCOL_VERSION,n as buildQoderCliFlagSettings,l as buildQoderCliFlagSettingsArgs};
+var r="1.2.0";function i(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function n(e={}){let t={...e.settings??{}},o=e.aiCodeTracking?.installGitCommitHook;if(o!==void 0){let s=t.aiCodeTracking;t.aiCodeTracking={...i(s)?s:{},installGitCommitHook:o}}return t}function p(e={}){let t=n(e);return Object.keys(t).length===0?[]:["--settings",JSON.stringify(t)]}var l={Main:"main",Plan:"plan",Task:"task",Compact:"compact",Title:"title",Suggestion:"suggestion",Generate:"generate",HookPrompt:"hook_prompt",Subagent:"subagent",WebFetch:"web_fetch",ImageGen:"image_gen",Compression:"compression",Utility:"utility"};export{l as QoderModelPurpose,r as WIRE_PROTOCOL_VERSION,n as buildQoderCliFlagSettings,p as buildQoderCliFlagSettingsArgs};

package/dist/protocol/messages.d.ts

@@ -17,6 +17,13 @@ export type SDKAssistantMessage = {
     type: 'assistant';
     message: BetaMessage;
     parent_tool_use_id: string | null;
+    /**
+     * Present when qodercli synthesized this Assistant message from an API
+     * failure rather than a model response. Embedded hosts can use the marker to
+     * avoid rendering duplicate error text when the terminal Result already
+     * provides a structured error surface.
+     */
+    isApiErrorMessage?: true;
     /** Qoder model request ID, present only when explicitly enabled in the CLI. */
     request_id?: string;
     error?: SDKAssistantMessageError;
@@ -28,6 +35,16 @@ export type SDKAssistantMessage = {
     uuid: UUID;
     session_id: string;
 };
+export type SDKToolNonExecutionKind = 'user-rejected' | 'permission-rule' | 'automode-blocked' | 'automode-unavailable' | 'automode-parsing-error' | 'interrupted' | 'cancelled';
+/**
+ * Display-only metadata for a tool result whose tool did not run to
+ * completion. This wrapper-level field is never part of the model message.
+ */
+export type SDKToolResultMeta = {
+    id: string;
+    non_execution_kind: SDKToolNonExecutionKind;
+    user_feedback?: string;
+};
 export type SDKUserMessage = {
     type: 'user';
     message: MessageParam;
@@ -35,6 +52,7 @@ export type SDKUserMessage = {
     file_attachments?: SDKFileAttachment[];
     isSynthetic?: boolean;
     tool_use_result?: unknown;
+    tool_result_meta?: SDKToolResultMeta[];
     /**
      * Delivery priority. `next` is the default; `now` interrupts the active
      * turn, while `later` waits for the session to become idle.
@@ -57,6 +75,7 @@ export type SDKUserMessageReplay = {
     file_attachments?: SDKFileAttachment[];
     isSynthetic?: boolean;
     tool_use_result?: unknown;
+    tool_result_meta?: SDKToolResultMeta[];
     /**
      * Delivery priority. `next` is the default; `now` interrupts the active
      * turn, while `later` waits for the session to become idle.

package/dist/runtime-manifest.json

@@ -1,16 +1,16 @@
 {
   "version": 1,
   "brand": "global",
-  "sdkVersion": "1.0.21",
-  "qoderCliVersion": "1.1.20",
+  "sdkVersion": "1.0.23",
+  "qoderCliVersion": "1.1.23",
   "defaultTransport": "worker",
   "workerRuntime": {
     "packaged": false,
     "delivery": "install",
     "source": "qodercli-worker-runtime",
-    "url": "https://download.qoder.com/qodercli/releases/1.1.20/qodercli-worker-runtime-universal.tgz",
-    "artifactName": "qodercli-worker-runtime-universal.tgz",
-    "sdkVersion": "1.0.21",
-    "qoderCliVersion": "1.1.20"
+    "urlTemplate": "https://download.qoder.com/qodercli/releases/1.1.23/qodercli-worker-runtime-{target}.tgz",
+    "artifactNameTemplate": "qodercli-worker-runtime-{target}.tgz",
+    "sdkVersion": "1.0.23",
+    "qoderCliVersion": "1.1.23"
   }
 }

package/dist/types/messages.d.ts

@@ -9,13 +9,15 @@ import type { SDKMessage as ProtocolSDKMessage, SDKStatusMessage as ProtocolSDKS
 import type { MessageParam, UUID } from './common.js';
 import type { PermissionMode } from './permissions.js';
 import type { SessionKey } from '../session/session-store.js';
-export type { SDKAssistantMessage, SDKResultSuccess, SDKResultError, SDKResultMessage, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, } from '../protocol/index.js';
+export type { SDKAssistantMessage, SDKResultSuccess, SDKResultError, SDKResultMessage, SDKPartialAssistantMessage, SDKCompactBoundaryMessage, SDKAPIRetryMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKTaskNotificationMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKBackgroundTasksChangedMessage, SDKSessionStateChangedMessage, SDKSessionTitleChangedMessage, SDKFilesPersistedEvent, SDKElicitationCompleteMessage, SDKPromptSuggestionMessage, SDKCloudAgentEventMessage, SDKPermissionDenial, SDKToolNonExecutionKind, SDKToolResultMeta, } from '../protocol/index.js';
 export type SDKUserMessage = {
     type: 'user';
     message: MessageParam;
     parent_tool_use_id: string | null;
     isSynthetic?: boolean;
     tool_use_result?: unknown;
+    /** CLI-stamped display metadata for tool results that did not execute. */
+    tool_result_meta?: import('../protocol/index.js').SDKToolResultMeta[];
     /**
      * Delivery priority. `next` is the default; `now` interrupts the active
      * turn, while `later` waits for the session to become idle.

package/dist/types/model-policy-provider.d.ts

@@ -48,6 +48,16 @@ export interface ModelPolicyResult {
     });
     /** Optional per-request model policy parameters (contextWindow, reasoningEffort). */
     parameters?: Record<string, unknown>;
+    /**
+     * Optional routing scene label sent as the inference request body `task_id`.
+     * The server selects models by it; internal CLI tasks keep their own values.
+     */
+    taskId?: string;
+    /**
+     * Optional business sub-task label sent as `business.sub_task` on the
+     * inference request, used for billing/analytics. Not involved in routing.
+     */
+    subTask?: string;
 }
 /**
  * Host-registered callback for pull-mode model selection.

package/dist/types/options.d.ts

@@ -141,6 +141,25 @@ export type Options = {
     enableFileCheckpointing?: boolean;
     toolConfig?: ToolConfig;
     forkSession?: boolean;
+    /**
+     * When resuming, load the conversation chain only through this entry UUID.
+     * Use with `resume`; when combined with `forkSession`, the new session starts
+     * from this historical point while retaining its file checkpoint history.
+     * The UUID may identify any persisted chain entry, not only an assistant
+     * message. Use the last entry belonging to the turn that must be kept.
+     */
+    resumeSessionAt?: string;
+    /**
+     * With `resumeSessionAt`, declares the prompt UUID of the turn intended to be
+     * discarded. The CLI refuses the truncation if the discarded range contains
+     * unrelated work such as a queued prompt or task notification.
+     *
+     * A refusal is returned as an execution error whose message starts with
+     * `Resume rejected by --resume-drops-turn:`. Treat it as a deterministic
+     * stale-view conflict: resume without truncation to recover the new evidence
+     * instead of retrying the same request.
+     */
+    resumeDropsTurn?: string;
     hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
     onElicitation?: OnElicitation;
     /**

package/dist/types/session.d.ts

@@ -1,3 +1,4 @@
+import type { SDKToolResultMeta } from '../protocol/messages.js';
 export type SDKSessionInfo = {
     /** Unique session identifier (UUID). */
     sessionId: string;
@@ -31,6 +32,10 @@ export type SessionMessage = {
      * messages, depth-one subagents, and transcripts without this metadata.
      */
     parent_agent_id: string | null;
+    /** Present when qodercli persisted an Assistant synthesized from an API failure. */
+    isApiErrorMessage?: true;
+    /** CLI-stamped display metadata for tool results that did not execute. */
+    tool_result_meta?: SDKToolResultMeta[];
     /**
      * ISO 8601 timestamp of when this transcript entry was written to the
      * jsonl file. Mirrors the on-disk `timestamp` field. Optional because

package/dist/types/tools.d.ts

@@ -62,6 +62,20 @@ export type BashInput = {
     description?: string;
     run_in_background?: boolean;
 };
+export type BashToolBackgroundLaunchResult = {
+    kind: 'backgrounded';
+    pid: number;
+    taskId: string;
+    outputFile?: string;
+    command: string;
+    stdout?: string;
+    initialOutput: string;
+    backgroundReason?: 'user' | 'model' | 'timeout' | 'auto';
+    telemetryExecutionId?: string;
+    totalLines?: number;
+    totalBytes?: number;
+};
+export declare function isBashToolBackgroundLaunchResult(value: unknown): value is BashToolBackgroundLaunchResult;
 export type BashOutput = {
     stdout: string;
     stderr: string;
@@ -372,4 +386,4 @@ export type McpOutput = {
     isError?: boolean;
 };
 export type ToolInputSchemas = AgentInput | BashInput | FileReadInput | FileEditInput | FileWriteInput | GlobInput | GrepInput | WebFetchInput | WebSearchInput | AskUserQuestionInput | NotebookEditInput | TaskStopInput | TaskCreateInput | TaskGetInput | TaskUpdateInput | TaskListInput | ExitPlanModeInput | ConfigInput | EnterWorktreeInput | ExitWorktreeInput | TodoWriteInput | ListMcpResourcesInput | ReadMcpResourceInput | McpInput;
-export type ToolOutputSchemas = AgentOutput | BashOutput | FileReadOutput | FileEditOutput | FileWriteOutput | GlobOutput | GrepOutput | WebFetchOutput | WebSearchOutput | AskUserQuestionOutput | NotebookEditOutput | TaskStopOutput | TaskCreateOutput | TaskGetOutput | TaskUpdateOutput | TaskListOutput | ExitPlanModeOutput | ConfigOutput | EnterWorktreeOutput | ExitWorktreeOutput | TodoWriteOutput | ListMcpResourcesOutput | McpOutput;
+export type ToolOutputSchemas = AgentOutput | BashToolBackgroundLaunchResult | BashOutput | FileReadOutput | FileEditOutput | FileWriteOutput | GlobOutput | GrepOutput | WebFetchOutput | WebSearchOutput | AskUserQuestionOutput | NotebookEditOutput | TaskStopOutput | TaskCreateOutput | TaskGetOutput | TaskUpdateOutput | TaskListOutput | ExitPlanModeOutput | ConfigOutput | EnterWorktreeOutput | ExitWorktreeOutput | TodoWriteOutput | ListMcpResourcesOutput | McpOutput;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoder-ai/qoder-agent-sdk",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "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.20",
+  "qoderCliVersion": "1.1.23",
   "qoderSdkBrand": "global",
   "license": "SEE LICENSE IN LICENSE"
 }

package/scripts/postinstall.cjs

@@ -30,7 +30,6 @@ 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 REQUIRED_WORKER_RUNTIME_ASSETS = [path.join('vendor', 'ripgrep', 'x64-win32', 'rg.exe')];
 
 function isTruthy(value) {
   return value === '1' || value === 'true';
@@ -209,8 +208,36 @@ function getDownloadUrl() {
   return `${baseUrl}/${getArtifactName()}`;
 }
 
-function getWorkerRuntimeArtifactName(site = getCliSite()) {
-  return `${getCliArtifactPrefix(site)}-worker-runtime-universal.tgz`;
+function getWorkerRuntimeTarget(target = getPlatformTarget()) {
+  const [platform, arch] = target.split('-');
+  if (platform === 'darwin') return `darwin-${arch}`;
+  if (platform === 'linux') return `linux-${arch}`;
+  if (platform === 'windows') return `win32-${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`,
+  );
+}
+
+function getWorkerRuntimeArtifactName(site = getCliSite(), target = getPlatformTarget()) {
+  const workerTarget = getWorkerRuntimeTarget(target);
+  return `${getCliArtifactPrefix(site)}-worker-runtime-${workerTarget}.tgz`;
+}
+
+function getWorkerRuntimeArtifactNameTemplate(site = getCliSite()) {
+  return `${getCliArtifactPrefix(site)}-worker-runtime-{target}.tgz`;
+}
+
+function getWorkerRuntimeRequiredAssets(target = getPlatformTarget()) {
+  const workerTarget = getWorkerRuntimeTarget(target);
+  const [platform, arch] = workerTarget.split('-');
+  return [
+    path.join(
+      'vendor',
+      'ripgrep',
+      `${arch}-${platform}`,
+      platform === 'win32' ? 'rg.exe' : 'rg',
+    ),
+  ];
 }
 
 function hasWorkerRuntimeDownloadSiteOverride() {
@@ -231,6 +258,14 @@ function getManifestWorkerRuntimeDownloadUrl(manifest = readRuntimeManifest()) {
   return url ?? null;
 }
 
+function getManifestWorkerRuntimeDownloadUrlTemplate(manifest = readRuntimeManifest()) {
+  const workerRuntime = getManifestWorkerRuntime(manifest);
+  if (!workerRuntime || workerRuntime.packaged === true) return null;
+  return typeof workerRuntime.urlTemplate === 'string' && workerRuntime.urlTemplate.length > 0
+    ? workerRuntime.urlTemplate
+    : null;
+}
+
 function getManifestWorkerRuntimeSha256(manifest = readRuntimeManifest()) {
   const workerRuntime = getManifestWorkerRuntime(manifest);
   if (!workerRuntime || workerRuntime.packaged === true) return null;
@@ -246,30 +281,39 @@ function getManifestWorkerRuntimeSha256(manifest = readRuntimeManifest()) {
   return checksum ? checksum.trim().toLowerCase() : null;
 }
 
+function getWorkerRuntimeDownloadUrlTemplate() {
+  const version = getCliVersion();
+  const baseUrl = normalizeDownloadBaseUrl(getWorkerRuntimeDownloadBaseUrl(version), version);
+  return `${baseUrl}/${getWorkerRuntimeArtifactNameTemplate()}`;
+}
+
+function getWorkerRuntimeDefaultDownloadUrl() {
+  return getWorkerRuntimeDownloadUrlTemplate().replace(
+    '{target}',
+    getWorkerRuntimeTarget(),
+  );
+}
+
 function getWorkerRuntimeDownloadUrl() {
   if (process.env.QODER_WORKER_RUNTIME_URL) {
     return process.env.QODER_WORKER_RUNTIME_URL;
   }
 
-  const manifestUrl = hasWorkerRuntimeDownloadSiteOverride()
-    ? null
-    : getManifestWorkerRuntimeDownloadUrl();
-  if (manifestUrl) {
-    return manifestUrl;
+  if (!hasWorkerRuntimeDownloadSiteOverride()) {
+    const template = getManifestWorkerRuntimeDownloadUrlTemplate();
+    if (template) {
+      return template.replace('{target}', getWorkerRuntimeTarget());
+    }
+    const manifestUrl = getManifestWorkerRuntimeDownloadUrl();
+    if (manifestUrl) return manifestUrl;
   }
 
-  const version = getCliVersion();
-  const baseUrl = normalizeDownloadBaseUrl(getWorkerRuntimeDownloadBaseUrl(version), version);
-  return `${baseUrl}/${getWorkerRuntimeArtifactName()}`;
+  return getWorkerRuntimeDefaultDownloadUrl();
 }
 
 function getWorkerRuntimeExpectedSha256(url = getWorkerRuntimeDownloadUrl()) {
   const manifestUrl = getManifestWorkerRuntimeDownloadUrl();
-  if (manifestUrl && manifestUrl === url) {
-    return getManifestWorkerRuntimeSha256();
-  }
-
-  return null;
+  return manifestUrl === url ? getManifestWorkerRuntimeSha256() : null;
 }
 
 function getBundledDir() {
@@ -375,6 +419,15 @@ function isPackagedWorkerRuntimeCompatibleWithSite(site = getCliSite()) {
     runtimeInfo.build && typeof runtimeInfo.build === 'object' ? runtimeInfo.build : {};
   const actualProductName = buildInfo.productName;
   const actualSite = buildInfo.site;
+  const expectedVersion = getCliVersion();
+
+  if (runtimeInfo.version !== expectedVersion) {
+    return false;
+  }
+
+  if (runtimeInfo.profile !== 'platform' || runtimeInfo.target !== getWorkerRuntimeTarget()) {
+    return false;
+  }
 
   if (
     typeof actualProductName === 'string' &&
@@ -462,8 +515,10 @@ async function downloadFile(url, destPath) {
   console.log(`${LOG_PREFIX} Downloading: ${url}`);
   const response = await requestUrl(url);
   if (response.statusCode !== 200) {
+    const error = new Error(`Download failed: HTTP ${response.statusCode}`);
+    error.statusCode = response.statusCode;
     response.resume();
-    throw new Error(`Download failed: HTTP ${response.statusCode}`);
+    throw error;
   }
 
   await new Promise((resolve, reject) => {
@@ -506,6 +561,7 @@ async function downloadWithRetry(url, destPath, maxRetries = 2) {
       lastError = error;
       console.error(`${LOG_PREFIX} Download failed: ${error.message}`);
       fs.rmSync(destPath, { force: true });
+      if (error.statusCode === 404) break;
     }
   }
   throw lastError;
@@ -709,7 +765,7 @@ function assertWorkerRuntimeComplete(runtimeDir, sourceDescription) {
     throw new Error(`Worker runtime entry missing in ${sourceDescription}: ${runtimePath}`);
   }
 
-  const missingAssets = REQUIRED_WORKER_RUNTIME_ASSETS.filter(
+  const missingAssets = getWorkerRuntimeRequiredAssets().filter(
     (assetPath) => !fs.existsSync(path.join(runtimeDir, assetPath)),
   );
   if (missingAssets.length > 0) {
@@ -725,7 +781,49 @@ function assertWorkerRuntimeComplete(runtimeDir, sourceDescription) {
   return runtimePath;
 }
 
-function installExtractedWorkerRuntime(extractDir, workerDir) {
+function assertWorkerRuntimeIdentity(runtimeDir) {
+  const runtimeInfoPath = path.join(runtimeDir, 'runtime-info.json');
+  if (!fs.existsSync(runtimeInfoPath)) {
+    throw new Error(`Downloaded Worker runtime is missing identity metadata: ${runtimeInfoPath}`);
+  }
+
+  let runtimeInfo;
+  try {
+    runtimeInfo = JSON.parse(fs.readFileSync(runtimeInfoPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Downloaded Worker runtime has invalid identity metadata: ${error.message}`);
+  }
+
+  const expectedTarget = getWorkerRuntimeTarget();
+  const expectedSite = getCliSite();
+  const expectedProductName = getCliArtifactPrefix(expectedSite);
+  const expectedVersion = getCliVersion();
+  const mismatches = [];
+
+  if (runtimeInfo.profile !== 'platform') {
+    mismatches.push(`profile=${String(runtimeInfo.profile)} (expected platform)`);
+  }
+  if (runtimeInfo.target !== expectedTarget) {
+    mismatches.push(`target=${String(runtimeInfo.target)} (expected ${expectedTarget})`);
+  }
+  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?.productName !== expectedProductName) {
+    mismatches.push(
+      `productName=${String(runtimeInfo.build?.productName)} (expected ${expectedProductName})`,
+    );
+  }
+
+  if (mismatches.length > 0) {
+    throw new Error(`Downloaded Worker runtime identity mismatch: ${mismatches.join(', ')}`);
+  }
+}
+
+function installExtractedWorkerRuntime(extractDir, workerDir, options = {}) {
   const contentRoot = findWorkerRuntimeRoot(extractDir);
   if (!contentRoot) {
     throw new Error(
@@ -733,6 +831,9 @@ function installExtractedWorkerRuntime(extractDir, workerDir) {
     );
   }
   assertWorkerRuntimeComplete(contentRoot, contentRoot);
+  if (options.validateIdentity === true) {
+    assertWorkerRuntimeIdentity(contentRoot);
+  }
 
   fs.rmSync(workerDir, { recursive: true, force: true });
   copyDirContents(contentRoot, workerDir);
@@ -744,24 +845,36 @@ function installExtractedWorkerRuntime(extractDir, workerDir) {
   return runtimePath;
 }
 
-async function installWorkerRuntimeFromDownload() {
-  const url = getWorkerRuntimeDownloadUrl();
-  const expectedSha256 = getWorkerRuntimeExpectedSha256(url);
+async function downloadAndInstallWorkerRuntime(workerDir, options = {}) {
+  const url = options.urlOverride ?? getWorkerRuntimeDownloadUrl();
+  const expectedSha256 = options.urlOverride ? 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');
 
   try {
+    fs.mkdirSync(extractDir, { recursive: true });
     await downloadWithRetry(url, archivePath);
     await verifyChecksum(url, archivePath, expectedSha256);
-    fs.mkdirSync(extractDir, { recursive: true });
     await extractArchive(archivePath, extractDir);
-    return installExtractedWorkerRuntime(extractDir, getPackagedWorkerRuntimeDir());
+    return {
+      runtimePath: installExtractedWorkerRuntime(extractDir, workerDir, {
+        validateIdentity: true,
+      }),
+      url,
+    };
   } finally {
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 }
 
+async function installWorkerRuntimeFromDownload() {
+  const installed = await downloadAndInstallWorkerRuntime(
+    getPackagedWorkerRuntimeDir(),
+  );
+  return installed.runtimePath;
+}
+
 async function main() {
   if (isTruthy(process.env.QODER_SKIP_DOWNLOAD)) {
     console.log(`${LOG_PREFIX} QODER_SKIP_DOWNLOAD is set, skipping runtime downloads.`);
@@ -849,6 +962,8 @@ if (require.main === module) {
 }
 
 module.exports = {
+  assertWorkerRuntimeIdentity,
+  downloadAndInstallWorkerRuntime,
   downloadWithRetry,
   extractArchive,
   getTarExtractInvocation,
@@ -870,8 +985,13 @@ module.exports = {
   getDefaultRuntimeTransport,
   getWorkerRuntimeExpectedSha256,
   getWorkerRuntimeArtifactName,
+  getWorkerRuntimeArtifactNameTemplate,
   getWorkerRuntimeDownloadBaseUrl,
   getWorkerRuntimeDownloadUrl,
+  getWorkerRuntimeDownloadUrlTemplate,
+  getWorkerRuntimeRequiredAssets,
+  getWorkerRuntimeTarget,
+  getManifestWorkerRuntimeDownloadUrlTemplate,
   hasPackagedWorkerRuntime,
   installExtractedContents,
   installExtractedWorkerRuntime,