@polka-codes/core 0.8.2 → 0.8.4

package/dist/_tsup-dts-rollup.d.ts

@@ -774,64 +774,122 @@ export declare class DeepSeekService extends AiServiceBase {
 declare const _default: {
     handler: ToolHandler<{
         readonly name: "ask_followup_question";
-        readonly description: "Whenever you need extra details or clarification to complete the task, pose a direct question to the user. Use this tool sparingly to avoid excessive back-and-forth. If helpful, offer multiple-choice options or examples to guide the user’s response.";
+        readonly description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.";
         readonly parameters: [{
-            readonly name: "question";
-            readonly description: "The question to ask the user. This should be a clear, specific question that addresses the information you need.";
+            readonly name: "questions";
+            readonly description: "One or more follow-up questions you need answered before you can continue.";
             readonly required: true;
-            readonly usageValue: "Your question here";
-        }, {
-            readonly name: "options";
-            readonly description: "A comma separated list of possible answers to the question. Ordered by preference. If not provided, the user will be prompted to provide an answer.";
-            readonly required: false;
-            readonly usageValue: "A comma separated list of possible answers (optional)";
+            readonly allowMultiple: true;
+            readonly children: [{
+                readonly name: "prompt";
+                readonly description: "The text of the question.";
+                readonly required: true;
+                readonly usageValue: "question text here";
+            }, {
+                readonly name: "options";
+                readonly description: "Ordered list of suggested answers (omit if none).";
+                readonly required: false;
+                readonly allowMultiple: true;
+                readonly usageValue: "suggested answer here";
+            }];
         }];
         readonly examples: [{
-            readonly description: "Request to ask a question";
+            readonly description: "Single clarifying question (no options)";
             readonly parameters: [{
-                readonly name: "question";
-                readonly value: "What is the name of the project?";
+                readonly name: "questions";
+                readonly value: {
+                    readonly prompt: "What is the target deployment environment?";
+                };
             }];
         }, {
-            readonly description: "Request to ask a question with options";
+            readonly description: "Single question with multiple-choice options";
             readonly parameters: [{
-                readonly name: "question";
-                readonly value: "What framework do you use?";
-            }, {
-                readonly name: "options";
-                readonly value: "React,Angular,Vue,Svelte";
+                readonly name: "questions";
+                readonly value: {
+                    readonly prompt: "Which frontend framework are you using?";
+                    readonly options: ["React", "Angular", "Vue", "Svelte"];
+                };
+            }];
+        }, {
+            readonly description: "Two related questions in one call";
+            readonly parameters: [{
+                readonly name: "questions";
+                readonly value: [{
+                    readonly prompt: "What type of application are you building?";
+                }, {
+                    readonly prompt: "Preferred programming language?";
+                    readonly options: ["JavaScript", "TypeScript", "Python", "Java"];
+                }];
+            }];
+        }, {
+            readonly description: "Binary (yes/no) confirmation";
+            readonly parameters: [{
+                readonly name: "questions";
+                readonly value: {
+                    readonly prompt: "Is it acceptable to refactor existing tests to improve performance?";
+                    readonly options: ["Yes", "No"];
+                };
             }];
         }];
         readonly permissionLevel: PermissionLevel.None;
     }, InteractionProvider>;
     isAvailable: (provider: InteractionProvider) => boolean;
     name: "ask_followup_question";
-    description: "Whenever you need extra details or clarification to complete the task, pose a direct question to the user. Use this tool sparingly to avoid excessive back-and-forth. If helpful, offer multiple-choice options or examples to guide the user’s response.";
+    description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.";
     parameters: [{
-        readonly name: "question";
-        readonly description: "The question to ask the user. This should be a clear, specific question that addresses the information you need.";
+        readonly name: "questions";
+        readonly description: "One or more follow-up questions you need answered before you can continue.";
         readonly required: true;
-        readonly usageValue: "Your question here";
-    }, {
-        readonly name: "options";
-        readonly description: "A comma separated list of possible answers to the question. Ordered by preference. If not provided, the user will be prompted to provide an answer.";
-        readonly required: false;
-        readonly usageValue: "A comma separated list of possible answers (optional)";
+        readonly allowMultiple: true;
+        readonly children: [{
+            readonly name: "prompt";
+            readonly description: "The text of the question.";
+            readonly required: true;
+            readonly usageValue: "question text here";
+        }, {
+            readonly name: "options";
+            readonly description: "Ordered list of suggested answers (omit if none).";
+            readonly required: false;
+            readonly allowMultiple: true;
+            readonly usageValue: "suggested answer here";
+        }];
     }];
     examples: [{
-        readonly description: "Request to ask a question";
+        readonly description: "Single clarifying question (no options)";
         readonly parameters: [{
-            readonly name: "question";
-            readonly value: "What is the name of the project?";
+            readonly name: "questions";
+            readonly value: {
+                readonly prompt: "What is the target deployment environment?";
+            };
         }];
     }, {
-        readonly description: "Request to ask a question with options";
+        readonly description: "Single question with multiple-choice options";
         readonly parameters: [{
-            readonly name: "question";
-            readonly value: "What framework do you use?";
-        }, {
-            readonly name: "options";
-            readonly value: "React,Angular,Vue,Svelte";
+            readonly name: "questions";
+            readonly value: {
+                readonly prompt: "Which frontend framework are you using?";
+                readonly options: ["React", "Angular", "Vue", "Svelte"];
+            };
+        }];
+    }, {
+        readonly description: "Two related questions in one call";
+        readonly parameters: [{
+            readonly name: "questions";
+            readonly value: [{
+                readonly prompt: "What type of application are you building?";
+            }, {
+                readonly prompt: "Preferred programming language?";
+                readonly options: ["JavaScript", "TypeScript", "Python", "Java"];
+            }];
+        }];
+    }, {
+        readonly description: "Binary (yes/no) confirmation";
+        readonly parameters: [{
+            readonly name: "questions";
+            readonly value: {
+                readonly prompt: "Is it acceptable to refactor existing tests to improve performance?";
+                readonly options: ["Yes", "No"];
+            };
         }];
     }];
     permissionLevel: PermissionLevel.None;
@@ -1354,23 +1412,23 @@ export { _default_3 as delegate_alias_2 }
 declare const _default_4: {
     handler: ToolHandler<{
         readonly name: "execute_command";
-        readonly description: "Request to execute a CLI command on the system. Use this when you need to perform system operations or run specific commands to accomplish any step in the user's task. You must tailor your command to the user's system and provide a clear explanation of what the command does. Prefer to execute complex CLI commands over creating executable scripts, as they are more flexible and easier to run. Commands will also be executed in the project root directory regardless of executed commands in previous tool uses.";
+        readonly description: "Run a single CLI command. The command is always executed in the project-root working directory (regardless of earlier commands). Prefer one-off shell commands over wrapper scripts for flexibility. After an `execute_command` call, no other tool calls are allowed in the same assistant response.";
         readonly parameters: [{
             readonly name: "command";
-            readonly description: "The CLI command to execute. This should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions.";
+            readonly description: "The exact command to run (valid for the current OS). It must be correctly formatted and free of harmful instructions.";
             readonly required: true;
-            readonly usageValue: "Your command here";
+            readonly usageValue: "your-command-here";
         }, {
             readonly name: "requires_approval";
-            readonly description: "A boolean indicating whether this command requires explicit user approval before execution in case the user has auto-approve mode enabled. Set to 'true' for potentially impactful operations like installing/uninstalling packages, deleting/overwriting files, system configuration changes, network operations, or any commands that could have unintended side effects. Set to 'false' for safe operations like reading files/directories, running development servers, building projects, and other non-destructive operations.";
+            readonly description: "Set to `true` for commands that install/uninstall software, modify or delete files, change system settings, perform network operations, or have other side effects. Use `false` for safe, read-only, or purely local development actions (e.g., listing files, make a build, running tests).";
             readonly required: false;
-            readonly usageValue: "true or false";
+            readonly usageValue: "true | false";
         }];
         readonly examples: [{
-            readonly description: "Request to execute a command";
+            readonly description: "Make a build";
             readonly parameters: [{
                 readonly name: "command";
-                readonly value: "npm run dev";
+                readonly value: "npm run build";
             }, {
                 readonly name: "requires_approval";
                 readonly value: "false";
@@ -1380,23 +1438,23 @@ declare const _default_4: {
     }, CommandProvider>;
     isAvailable: (provider: CommandProvider) => boolean;
     name: "execute_command";
-    description: "Request to execute a CLI command on the system. Use this when you need to perform system operations or run specific commands to accomplish any step in the user's task. You must tailor your command to the user's system and provide a clear explanation of what the command does. Prefer to execute complex CLI commands over creating executable scripts, as they are more flexible and easier to run. Commands will also be executed in the project root directory regardless of executed commands in previous tool uses.";
+    description: "Run a single CLI command. The command is always executed in the project-root working directory (regardless of earlier commands). Prefer one-off shell commands over wrapper scripts for flexibility. After an `execute_command` call, no other tool calls are allowed in the same assistant response.";
     parameters: [{
         readonly name: "command";
-        readonly description: "The CLI command to execute. This should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions.";
+        readonly description: "The exact command to run (valid for the current OS). It must be correctly formatted and free of harmful instructions.";
         readonly required: true;
-        readonly usageValue: "Your command here";
+        readonly usageValue: "your-command-here";
     }, {
         readonly name: "requires_approval";
-        readonly description: "A boolean indicating whether this command requires explicit user approval before execution in case the user has auto-approve mode enabled. Set to 'true' for potentially impactful operations like installing/uninstalling packages, deleting/overwriting files, system configuration changes, network operations, or any commands that could have unintended side effects. Set to 'false' for safe operations like reading files/directories, running development servers, building projects, and other non-destructive operations.";
+        readonly description: "Set to `true` for commands that install/uninstall software, modify or delete files, change system settings, perform network operations, or have other side effects. Use `false` for safe, read-only, or purely local development actions (e.g., listing files, make a build, running tests).";
         readonly required: false;
-        readonly usageValue: "true or false";
+        readonly usageValue: "true | false";
     }];
     examples: [{
-        readonly description: "Request to execute a command";
+        readonly description: "Make a build";
         readonly parameters: [{
             readonly name: "command";
-            readonly value: "npm run dev";
+            readonly value: "npm run build";
         }, {
             readonly name: "requires_approval";
             readonly value: "false";
@@ -1861,6 +1919,11 @@ declare const generateProjectConfig: (agent: MultiAgent, params: unknown) => Pro
 export { generateProjectConfig }
 export { generateProjectConfig as generateProjectConfig_alias_1 }
 
+declare const getArray: <T extends string>(args: Partial<Record<T, ToolParameterValue>> | ToolParameterValue, name: T, defaultValue?: ToolParameterValue[]) => ToolParameterValue[];
+export { getArray }
+export { getArray as getArray_alias_1 }
+export { getArray as getArray_alias_2 }
+
 /**
  * Get the available tools based on the provider and agent availability
  * @param provider The provider to use.
@@ -1880,7 +1943,7 @@ declare const getAvailableTools: ({ provider, allTools, hasAgent, permissionLeve
 export { getAvailableTools }
 export { getAvailableTools as getAvailableTools_alias_1 }
 
-declare const getBoolean: <T extends string>(args: Partial<Record<T, string>>, name: T, defaultValue?: boolean) => boolean;
+declare const getBoolean: <T extends string>(args: Partial<Record<T, ToolParameterValue>>, name: T, defaultValue?: boolean) => boolean;
 export { getBoolean }
 export { getBoolean as getBoolean_alias_1 }
 export { getBoolean as getBoolean_alias_2 }
@@ -1890,7 +1953,7 @@ export { GetInput }
 export { GetInput as GetInput_alias_1 }
 export { GetInput as GetInput_alias_2 }
 
-declare const getInt: <T extends string>(args: Partial<Record<T, string>>, name: T, defaultValue?: number) => number;
+declare const getInt: <T extends string>(args: Partial<Record<T, ToolParameterValue>>, name: T, defaultValue?: number) => number;
 export { getInt }
 export { getInt as getInt_alias_1 }
 export { getInt as getInt_alias_2 }
@@ -1900,12 +1963,12 @@ export { GetOutput }
 export { GetOutput as GetOutput_alias_1 }
 export { GetOutput as GetOutput_alias_2 }
 
-declare const getString: <T extends string>(args: Partial<Partial<Record<T, string>>>, name: T, defaultValue?: string) => string;
+declare const getString: <T extends string>(args: Partial<Record<T, string>> | ToolParameterValue, name: T, defaultValue?: string) => string;
 export { getString }
 export { getString as getString_alias_1 }
 export { getString as getString_alias_2 }
 
-declare const getStringArray: <T extends string>(args: Partial<Record<T, string>>, name: T, defaultValue?: string[]) => string[];
+declare const getStringArray: <T extends string>(args: Partial<Record<T, ToolParameterValue>>, name: T, defaultValue?: string[]) => string[];
 export { getStringArray }
 export { getStringArray as getStringArray_alias_1 }
 export { getStringArray as getStringArray_alias_2 }
@@ -2229,6 +2292,34 @@ declare type Output = {
  * //   {type: "tool_use", name: "search", params: {query: "cats"}},
  * //   {type: "text", content: "Here are the results"}
  * // ]
+ *
+ * // Array mode (multiple occurrences of the same parameter)
+ * parseAssistantMessage(
+ *   `<tool_read_file>
+ *     <tool_parameter_path>test.ts</tool_parameter_path>
+ *     <tool_parameter_path>main.ts</tool_parameter_path>
+ *   </tool_read_file>`,
+ *   tools,
+ *   "tool_"
+ * )
+ * // Returns: [
+ * //   {type: "tool_use", name: "read_file", params: {path: ["test.ts", "main.ts"]}}
+ * // ]
+ *
+ * // Nested objects
+ * parseAssistantMessage(
+ *   `<tool_example>
+ *     <tool_parameter_key>
+ *       <tool_parameter_key2>value</tool_parameter_key2>
+ *       <tool_parameter_key3>value2</tool_parameter_key3>
+ *     </tool_parameter_key>
+ *   </tool_example>`,
+ *   tools,
+ *   "tool_"
+ * )
+ * // Returns: [
+ * //   {type: "tool_use", name: "example", params: {key: {key2: "value", key3: "value2"}}}
+ * // ]
  */
 declare function parseAssistantMessage(assistantMessage: string, tools: ToolInfo[], toolNamePrefix: string): AssistantMessageContent[];
 export { parseAssistantMessage }
@@ -2467,13 +2558,13 @@ declare type ToolExample = {
     description: string;
     parameters: {
         name: string;
-        value: string;
+        value: ToolParameterValue;
     }[];
 };
 export { ToolExample }
 export { ToolExample as ToolExample_alias_1 }
 
-declare type ToolHandler<T extends ToolInfo, P> = (provider: P, args: Partial<Record<T['parameters'][number]['name'], string>>) => Promise<ToolResponse>;
+declare type ToolHandler<T extends ToolInfo, P> = (provider: P, args: Partial<Record<T['parameters'][number]['name'], ToolParameterValue>>) => Promise<ToolResponse>;
 export { ToolHandler }
 export { ToolHandler as ToolHandler_alias_1 }
 
@@ -2489,32 +2580,61 @@ export { ToolInfo as ToolInfo_alias_1 }
 
 export declare const toolInfo: {
     readonly name: "ask_followup_question";
-    readonly description: "Whenever you need extra details or clarification to complete the task, pose a direct question to the user. Use this tool sparingly to avoid excessive back-and-forth. If helpful, offer multiple-choice options or examples to guide the user’s response.";
+    readonly description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.";
     readonly parameters: [{
-        readonly name: "question";
-        readonly description: "The question to ask the user. This should be a clear, specific question that addresses the information you need.";
+        readonly name: "questions";
+        readonly description: "One or more follow-up questions you need answered before you can continue.";
         readonly required: true;
-        readonly usageValue: "Your question here";
-    }, {
-        readonly name: "options";
-        readonly description: "A comma separated list of possible answers to the question. Ordered by preference. If not provided, the user will be prompted to provide an answer.";
-        readonly required: false;
-        readonly usageValue: "A comma separated list of possible answers (optional)";
+        readonly allowMultiple: true;
+        readonly children: [{
+            readonly name: "prompt";
+            readonly description: "The text of the question.";
+            readonly required: true;
+            readonly usageValue: "question text here";
+        }, {
+            readonly name: "options";
+            readonly description: "Ordered list of suggested answers (omit if none).";
+            readonly required: false;
+            readonly allowMultiple: true;
+            readonly usageValue: "suggested answer here";
+        }];
     }];
     readonly examples: [{
-        readonly description: "Request to ask a question";
+        readonly description: "Single clarifying question (no options)";
         readonly parameters: [{
-            readonly name: "question";
-            readonly value: "What is the name of the project?";
+            readonly name: "questions";
+            readonly value: {
+                readonly prompt: "What is the target deployment environment?";
+            };
         }];
     }, {
-        readonly description: "Request to ask a question with options";
+        readonly description: "Single question with multiple-choice options";
         readonly parameters: [{
-            readonly name: "question";
-            readonly value: "What framework do you use?";
-        }, {
-            readonly name: "options";
-            readonly value: "React,Angular,Vue,Svelte";
+            readonly name: "questions";
+            readonly value: {
+                readonly prompt: "Which frontend framework are you using?";
+                readonly options: ["React", "Angular", "Vue", "Svelte"];
+            };
+        }];
+    }, {
+        readonly description: "Two related questions in one call";
+        readonly parameters: [{
+            readonly name: "questions";
+            readonly value: [{
+                readonly prompt: "What type of application are you building?";
+            }, {
+                readonly prompt: "Preferred programming language?";
+                readonly options: ["JavaScript", "TypeScript", "Python", "Java"];
+            }];
+        }];
+    }, {
+        readonly description: "Binary (yes/no) confirmation";
+        readonly parameters: [{
+            readonly name: "questions";
+            readonly value: {
+                readonly prompt: "Is it acceptable to refactor existing tests to improve performance?";
+                readonly options: ["Yes", "No"];
+            };
         }];
     }];
     readonly permissionLevel: PermissionLevel.None;
@@ -2736,23 +2856,23 @@ export declare const toolInfo_alias_2: {
 
 export declare const toolInfo_alias_3: {
     readonly name: "execute_command";
-    readonly description: "Request to execute a CLI command on the system. Use this when you need to perform system operations or run specific commands to accomplish any step in the user's task. You must tailor your command to the user's system and provide a clear explanation of what the command does. Prefer to execute complex CLI commands over creating executable scripts, as they are more flexible and easier to run. Commands will also be executed in the project root directory regardless of executed commands in previous tool uses.";
+    readonly description: "Run a single CLI command. The command is always executed in the project-root working directory (regardless of earlier commands). Prefer one-off shell commands over wrapper scripts for flexibility. After an `execute_command` call, no other tool calls are allowed in the same assistant response.";
     readonly parameters: [{
         readonly name: "command";
-        readonly description: "The CLI command to execute. This should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions.";
+        readonly description: "The exact command to run (valid for the current OS). It must be correctly formatted and free of harmful instructions.";
         readonly required: true;
-        readonly usageValue: "Your command here";
+        readonly usageValue: "your-command-here";
     }, {
         readonly name: "requires_approval";
-        readonly description: "A boolean indicating whether this command requires explicit user approval before execution in case the user has auto-approve mode enabled. Set to 'true' for potentially impactful operations like installing/uninstalling packages, deleting/overwriting files, system configuration changes, network operations, or any commands that could have unintended side effects. Set to 'false' for safe operations like reading files/directories, running development servers, building projects, and other non-destructive operations.";
+        readonly description: "Set to `true` for commands that install/uninstall software, modify or delete files, change system settings, perform network operations, or have other side effects. Use `false` for safe, read-only, or purely local development actions (e.g., listing files, make a build, running tests).";
         readonly required: false;
-        readonly usageValue: "true or false";
+        readonly usageValue: "true | false";
     }];
     readonly examples: [{
-        readonly description: "Request to execute a command";
+        readonly description: "Make a build";
         readonly parameters: [{
             readonly name: "command";
-            readonly value: "npm run dev";
+            readonly value: "npm run build";
         }, {
             readonly name: "requires_approval";
             readonly value: "false";
@@ -2930,11 +3050,19 @@ declare type ToolParameter = {
     name: string;
     description: string;
     required: boolean;
-    usageValue: string;
+    usageValue?: string;
+    allowMultiple?: boolean;
+    children?: ToolParameter[];
 };
 export { ToolParameter }
 export { ToolParameter as ToolParameter_alias_1 }
 
+declare type ToolParameterValue = string | {
+    [key: string]: ToolParameterValue;
+} | ToolParameterValue[];
+export { ToolParameterValue }
+export { ToolParameterValue as ToolParameterValue_alias_1 }
+
 declare type ToolProvider = FilesystemProvider & CommandProvider & InteractionProvider;
 export { ToolProvider }
 export { ToolProvider as ToolProvider_alias_1 }
@@ -3039,7 +3167,7 @@ export { ToolResponseType as ToolResponseType_alias_1 }
 declare interface ToolUse {
     type: 'tool_use';
     name: string;
-    params: Record<string, string>;
+    params: Record<string, any>;
 }
 export { ToolUse }
 export { ToolUse as ToolUse_alias_1 }

package/dist/index.d.ts

@@ -100,6 +100,7 @@ export { AiToolDefinition } from './_tsup-dts-rollup.js';
 export { GetInput } from './_tsup-dts-rollup.js';
 export { GetOutput } from './_tsup-dts-rollup.js';
 export { ToolParameter } from './_tsup-dts-rollup.js';
+export { ToolParameterValue } from './_tsup-dts-rollup.js';
 export { ToolExample } from './_tsup-dts-rollup.js';
 export { PermissionLevel } from './_tsup-dts-rollup.js';
 export { ToolInfo } from './_tsup-dts-rollup.js';
@@ -123,3 +124,4 @@ export { getString } from './_tsup-dts-rollup.js';
 export { getStringArray } from './_tsup-dts-rollup.js';
 export { getBoolean } from './_tsup-dts-rollup.js';
 export { getInt } from './_tsup-dts-rollup.js';
+export { getArray } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -987,10 +987,16 @@ ${search}`);
 
 // src/tools/utils/getArg.ts
 var getString = (args, name, defaultValue) => {
+  if (typeof args !== "object" || Array.isArray(args)) {
+    throw new Error(`Invalid argument type: ${name} ${args}`);
+  }
   const ret = args[name] ?? defaultValue;
   if (ret === void 0) {
     throw new Error(`Missing required argument: ${name}`);
   }
+  if (typeof ret !== "string") {
+    throw new Error(`Invalid argument type: ${name} ${ret}`);
+  }
   return ret;
 };
 var getStringArray = (args, name, defaultValue) => {
@@ -1004,6 +1010,9 @@ var getStringArray = (args, name, defaultValue) => {
   if (ret === "") {
     return [];
   }
+  if (typeof ret !== "string") {
+    throw new Error(`Invalid argument type: ${name} ${ret}`);
+  }
   return ret.split(",").map((s) => s.trim());
 };
 var getBoolean = (args, name, defaultValue) => {
@@ -1014,13 +1023,16 @@ var getBoolean = (args, name, defaultValue) => {
     }
     return defaultValue;
   }
+  if (typeof ret !== "string") {
+    throw new Error(`Invalid argument type: ${name} ${ret}`);
+  }
   switch (ret.toLowerCase()) {
     case "true":
       return true;
     case "false":
       return false;
     default:
-      throw new Error(`Invalid argument value: ${name}`);
+      throw new Error(`Invalid argument value: ${name} ${ret}`);
   }
 };
 var getInt = (args, name, defaultValue) => {
@@ -1031,51 +1043,105 @@ var getInt = (args, name, defaultValue) => {
     }
     return defaultValue;
   }
+  if (typeof ret !== "string") {
+    throw new Error(`Invalid argument type: ${name} ${ret}`);
+  }
   const parsed = Number.parseInt(ret);
   if (Number.isNaN(parsed)) {
-    throw new Error(`Invalid argument value: ${name}`);
+    throw new Error(`Invalid argument value: ${name} ${ret}`);
   }
   return parsed;
 };
+var getArray = (args, name, defaultValue) => {
+  if (typeof args !== "object" || Array.isArray(args)) {
+    throw new Error(`Invalid argument type: ${name} ${args}`);
+  }
+  const ret = args[name];
+  if (ret === void 0) {
+    if (defaultValue === void 0) {
+      throw new Error(`Missing required argument: ${name}`);
+    }
+    return defaultValue;
+  }
+  if (Array.isArray(ret)) {
+    return ret;
+  }
+  return [ret];
+};
 
 // src/tools/askFollowupQuestion.ts
 var toolInfo = {
   name: "ask_followup_question",
-  description: "Whenever you need extra details or clarification to complete the task, pose a direct question to the user. Use this tool sparingly to avoid excessive back-and-forth. If helpful, offer multiple-choice options or examples to guide the user\u2019s response.",
+  description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.",
   parameters: [
     {
-      name: "question",
-      description: "The question to ask the user. This should be a clear, specific question that addresses the information you need.",
+      name: "questions",
+      description: "One or more follow-up questions you need answered before you can continue.",
       required: true,
-      usageValue: "Your question here"
-    },
-    {
-      name: "options",
-      description: "A comma separated list of possible answers to the question. Ordered by preference. If not provided, the user will be prompted to provide an answer.",
-      required: false,
-      usageValue: "A comma separated list of possible answers (optional)"
+      allowMultiple: true,
+      children: [
+        {
+          name: "prompt",
+          description: "The text of the question.",
+          required: true,
+          usageValue: "question text here"
+        },
+        {
+          name: "options",
+          description: "Ordered list of suggested answers (omit if none).",
+          required: false,
+          allowMultiple: true,
+          usageValue: "suggested answer here"
+        }
+      ]
     }
   ],
   examples: [
     {
-      description: "Request to ask a question",
+      description: "Single clarifying question (no options)",
       parameters: [
         {
-          name: "question",
-          value: "What is the name of the project?"
+          name: "questions",
+          value: { prompt: "What is the target deployment environment?" }
         }
       ]
     },
     {
-      description: "Request to ask a question with options",
+      description: "Single question with multiple-choice options",
       parameters: [
         {
-          name: "question",
-          value: "What framework do you use?"
-        },
+          name: "questions",
+          value: {
+            prompt: "Which frontend framework are you using?",
+            options: ["React", "Angular", "Vue", "Svelte"]
+          }
+        }
+      ]
+    },
+    {
+      description: "Two related questions in one call",
+      parameters: [
         {
-          name: "options",
-          value: "React,Angular,Vue,Svelte"
+          name: "questions",
+          value: [
+            { prompt: "What type of application are you building?" },
+            {
+              prompt: "Preferred programming language?",
+              options: ["JavaScript", "TypeScript", "Python", "Java"]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      description: "Binary (yes/no) confirmation",
+      parameters: [
+        {
+          name: "questions",
+          value: {
+            prompt: "Is it acceptable to refactor existing tests to improve performance?",
+            options: ["Yes", "No"]
+          }
         }
       ]
     }
@@ -1089,13 +1155,25 @@ var handler = async (provider, args) => {
       message: "Not possible to ask followup question. Abort."
     };
   }
-  const question = getString(args, "question");
-  const options = getStringArray(args, "options", []);
-  const answer = await provider.askFollowupQuestion(question, options);
+  const questions = getArray(args, "questions");
+  if (!questions || questions.length === 0) {
+    return {
+      type: "Error" /* Error */,
+      message: "No questions provided"
+    };
+  }
+  const answers = [];
+  for (const question of questions) {
+    const prompt6 = getString(question, "prompt");
+    const options = getArray(question, "options", []);
+    const answer = await provider.askFollowupQuestion(prompt6, options);
+    answers.push(`<ask_followup_question_answer question="${prompt6}">
+${answer}
+</ask_followup_question_answer>`);
+  }
   return {
     type: "Reply" /* Reply */,
-    message: `<ask_followup_question_question>${question}</ask_followup_question_question>
-<ask_followup_question_answer>${answer}</ask_followup_question_answer>`
+    message: answers.join("\n")
   };
 };
 var isAvailable = (provider) => {
@@ -1236,33 +1314,27 @@ var delegate_default = {
 // src/tools/executeCommand.ts
 var toolInfo4 = {
   name: "execute_command",
-  description: `Request to execute a CLI command on the system. Use this when you need to perform system operations or run specific commands to accomplish any step in the user's task. You must tailor your command to the user's system and provide a clear explanation of what the command does. Prefer to execute complex CLI commands over creating executable scripts, as they are more flexible and easier to run. Commands will also be executed in the project root directory regardless of executed commands in previous tool uses.`,
+  description: "Run a single CLI command. The command is always executed in the project-root working directory (regardless of earlier commands). Prefer one-off shell commands over wrapper scripts for flexibility. After an `execute_command` call, no other tool calls are allowed in the same assistant response.",
   parameters: [
     {
       name: "command",
-      description: "The CLI command to execute. This should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions.",
+      description: "The exact command to run (valid for the current OS). It must be correctly formatted and free of harmful instructions.",
       required: true,
-      usageValue: "Your command here"
+      usageValue: "your-command-here"
     },
     {
       name: "requires_approval",
-      description: `A boolean indicating whether this command requires explicit user approval before execution in case the user has auto-approve mode enabled. Set to 'true' for potentially impactful operations like installing/uninstalling packages, deleting/overwriting files, system configuration changes, network operations, or any commands that could have unintended side effects. Set to 'false' for safe operations like reading files/directories, running development servers, building projects, and other non-destructive operations.`,
+      description: "Set to `true` for commands that install/uninstall software, modify or delete files, change system settings, perform network operations, or have other side effects. Use `false` for safe, read-only, or purely local development actions (e.g., listing files, make a build, running tests).",
       required: false,
-      usageValue: "true or false"
+      usageValue: "true | false"
     }
   ],
   examples: [
     {
-      description: "Request to execute a command",
+      description: "Make a build",
       parameters: [
-        {
-          name: "command",
-          value: "npm run dev"
-        },
-        {
-          name: "requires_approval",
-          value: "false"
-        }
+        { name: "command", value: "npm run build" },
+        { name: "requires_approval", value: "false" }
       ]
     }
   ],
@@ -2230,6 +2302,22 @@ var getAvailableTools = ({
 };
 
 // src/Agent/parseAssistantMessage.ts
+function parseNestedParameters(content, parameterPrefix) {
+  const result = {};
+  const nestedParamRegex = new RegExp(`<${parameterPrefix}([^>]+)>([\\s\\S]*?)<\\/${parameterPrefix}\\1>`, "gs");
+  while (true) {
+    const match = nestedParamRegex.exec(content);
+    if (match === null) break;
+    const paramName = match[1];
+    const paramContent = match[2].trim();
+    if (paramContent.includes(`<${parameterPrefix}`)) {
+      result[paramName] = parseNestedParameters(paramContent, parameterPrefix);
+    } else {
+      result[paramName] = paramContent;
+    }
+  }
+  return result;
+}
 function parseAssistantMessage(assistantMessage, tools, toolNamePrefix) {
   const parameterPrefix = `${toolNamePrefix}parameter_`;
   const results = [];
@@ -2257,10 +2345,24 @@ function parseAssistantMessage(assistantMessage, tools, toolNamePrefix) {
       for (const param of tool.parameters) {
         const paramName = `${parameterPrefix}${param.name}`;
         const escapedParamName = paramName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const paramPattern = `<${escapedParamName}>([\\s\\S]*?)<\\/${escapedParamName}>`;
-        const paramMatch = fullTagContent.match(new RegExp(paramPattern, "s"));
-        if (paramMatch) {
-          params[param.name] = paramMatch[1].trim();
+        const paramRegex = new RegExp(`<${escapedParamName}>([\\s\\S]*?)<\\/${escapedParamName}>`, "gs");
+        const paramMatches = [];
+        while (true) {
+          const paramMatch = paramRegex.exec(fullTagContent);
+          if (paramMatch === null) break;
+          paramMatches.push(paramMatch[1].trim());
+        }
+        if (paramMatches.length > 0) {
+          if (paramMatches.length === 1) {
+            const paramContent = paramMatches[0];
+            if (paramContent.includes(`<${parameterPrefix}`)) {
+              params[param.name] = parseNestedParameters(paramContent, parameterPrefix);
+            } else {
+              params[param.name] = paramContent;
+            }
+          } else {
+            params[param.name] = paramMatches;
+          }
         }
       }
       results.push({
@@ -2292,6 +2394,18 @@ function parseAssistantMessage(assistantMessage, tools, toolNamePrefix) {
 }
 
 // src/Agent/prompts.ts
+var renderParameterValue = (key, value, parameterPrefix) => {
+  if (typeof value === "string") {
+    return `<${parameterPrefix}${key}>${value}</${parameterPrefix}${key}>`;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => renderParameterValue(key, v, parameterPrefix)).join("\n");
+  }
+  const inner = Object.entries(value).map(([key2, v]) => renderParameterValue(key2, v, parameterPrefix)).join("\n");
+  return `<${parameterPrefix}${key}>
+${inner}
+</${parameterPrefix}${key}>`;
+};
 var toolInfoPrompt = (tool, toolNamePrefix, parameterPrefix) => `
 ## ${toolNamePrefix}${tool.name}
 
@@ -2304,11 +2418,11 @@ Usage:
 <${toolNamePrefix}${tool.name}>
 ${tool.parameters.map((param) => `<${parameterPrefix}${param.name}>${param.usageValue}</${parameterPrefix}${param.name}>`).join("\n")}
 </${toolNamePrefix}${tool.name}>`;
-var toolInfoExamplesPrompt = (idx, tool, example, toolNamePrefix, parameterPrefix) => `
-## Example ${idx + 1}: ${example.description}
+var toolInfoExamplesPrompt = (tool, example, toolNamePrefix, parameterPrefix) => `
+## Example: ${example.description}
 
 <${toolNamePrefix}${tool.name}>
-${example.parameters.map((param) => `<${parameterPrefix}${param.name}>${param.value}</${parameterPrefix}${param.name}>`).join("\n")}
+${example.parameters.map((param) => `${renderParameterValue(param.name, param.value, parameterPrefix)}`).join("\n")}
 </${toolNamePrefix}${tool.name}>
 `;
 var toolUsePrompt = (tools, toolNamePrefix) => {
@@ -2316,7 +2430,6 @@ var toolUsePrompt = (tools, toolNamePrefix) => {
     return "";
   }
   const parameterPrefix = `${toolNamePrefix}parameter_`;
-  let exampleIndex = 0;
   return `
 ====
 
@@ -2334,11 +2447,39 @@ Tool use is formatted using XML-style tags. The tool name is enclosed in opening
 ...
 </${toolNamePrefix}tool_name>
 
-For example:
+## Array Parameters
+
+To create an array of values for a parameter, repeat the parameter tag multiple times:
+
+<${toolNamePrefix}process_file>
+<${parameterPrefix}path>test.ts</${parameterPrefix}path>
+<${parameterPrefix}path>main.ts</${parameterPrefix}path>
+</${toolNamePrefix}process_file>
+
+## Nested Object Parameters
+
+To create nested objects, nest parameter tags within other parameter tags:
+
+<${toolNamePrefix}example_tool>
+<${parameterPrefix}key>
+<${parameterPrefix}key2>value</${parameterPrefix}key2>
+<${parameterPrefix}key3>value2</${parameterPrefix}key3>
+</${parameterPrefix}key>
+</${toolNamePrefix}example_tool>
+
+You can also combine array parameters with nested objects:
 
-<${toolNamePrefix}read_file>
-<${parameterPrefix}path>src/main.js</${parameterPrefix}path>
-</${toolNamePrefix}read_file>
+<${toolNamePrefix}example_tool>
+<${parameterPrefix}key>
+<${parameterPrefix}key2>value</${parameterPrefix}key2>
+<${parameterPrefix}key3>value2</${parameterPrefix}key3>
+</${parameterPrefix}key>
+<${parameterPrefix}key>
+<${parameterPrefix}key2>value3</${parameterPrefix}key2>
+<${parameterPrefix}key3>value4</${parameterPrefix}key3>
+<${parameterPrefix}key3>value5</${parameterPrefix}key3>
+</${parameterPrefix}key>
+</${toolNamePrefix}example_tool>
 
 Always adhere to this format for the tool use to ensure proper parsing and execution.
 
@@ -2351,7 +2492,7 @@ ${tools.map((tool) => toolInfoPrompt(tool, toolNamePrefix, parameterPrefix)).joi
 ${tools.map((tool) => {
     let promp = "";
     for (const example of tool.examples ?? []) {
-      promp += toolInfoExamplesPrompt(exampleIndex++, tool, example, toolNamePrefix, parameterPrefix);
+      promp += toolInfoExamplesPrompt(tool, example, toolNamePrefix, parameterPrefix);
     }
     return promp;
   }).join("")}
@@ -3997,6 +4138,7 @@ export {
   generateGitCommitMessage,
   generateGithubPullRequestDetails,
   generateProjectConfig,
+  getArray,
   getAvailableTools,
   getBoolean,
   getInt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polka-codes/core",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "license": "AGPL-3.0",
   "author": "github@polka.codes",
   "type": "module",