@polka-codes/core 0.8.3 → 0.8.5

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
 
-<${toolNamePrefix}read_file>
-<${parameterPrefix}path>src/main.js</${parameterPrefix}path>
-</${toolNamePrefix}read_file>
+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}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("")}
@@ -3104,7 +3245,7 @@ You have access to two tools for working with files: **${toolNamePrefix}write_to
 
 ## Important Considerations
 
-- Using ${toolNamePrefix}write_to_file requires providing the file\u2019s complete final content.
+- Using ${toolNamePrefix}write_to_file requires providing the file's complete final content.
 - If you only need to make small changes to an existing file, consider using ${toolNamePrefix}replace_in_file instead to avoid unnecessarily rewriting the entire file.
 - While ${toolNamePrefix}write_to_file should not be your default choice, don't hesitate to use it when the situation truly calls for it.
 
@@ -3117,12 +3258,12 @@ You have access to two tools for working with files: **${toolNamePrefix}write_to
 ## When to Use
 
 - Small, localized changes like updating a few lines, function implementations, changing variable names, modifying a section of text, etc.
-- Targeted improvements where only specific portions of the file\u2019s content needs to be altered.
+- Targeted improvements where only specific portions of the file's content needs to be altered.
 - Especially useful for long files where much of the file will remain unchanged.
 
 ## Advantages
 
-- More efficient for minor edits, since you don\u2019t need to supply the entire file content.
+- More efficient for minor edits, since you don't need to supply the entire file content.
 - Reduces the chance of errors that can occur when overwriting large files.
 
 # Choosing the Appropriate Tool
@@ -3148,41 +3289,39 @@ var rules = (toolNamePrefix) => `
 
 RULES
 
-- You may use \`cd\` to enter any child directory within the current working directory. For example, \`cd myChildDir\`. But you may never move to a parent directory or any directory outside your current path. For example, do not use \`cd ..\`, \`cd /\`, or any absolute path.
-- Always work with relative path names, and never use absolute paths.
-- When generating code or test or any file that support comments, add a comment on top of the file with a description of the file's purpose and a note that this file is generated by "polka.codes".
-- When generate text file such as README.md, add a footer indicating this file is generated by "polka.codes".
-- Before using the ${toolNamePrefix}execute_command tool, you must first think about the SYSTEM INFORMATION context provided to understand the user's environment and tailor your commands to ensure they are compatible with their system. You must also consider if the command you need to run should be executed in a specific directory outside of the current working directory, and if so prepend with \`cd\`'ing into that directory && then executing the command (as one command). For example, if you needed to run \`npm install\` in a project that's not in the current working directory, you would need to prepend with a \`cd\` i.e. pseudocode for this would be \`cd (path to project) && (command, in this case npm install)\`. However, you can only cd into child directory, but never parent directory or root directory or home directory.
-- When using the ${toolNamePrefix}search_files tool, craft your regex patterns carefully to balance specificity and flexibility. Based on the user's task you may use it to find code patterns, TODO comments, function definitions, or any text-based information across the project. The results include context, so analyze the surrounding code to better understand the matches. Leverage the ${toolNamePrefix}search_files tool in combination with other tools for more comprehensive analysis. For example, use it to find specific code patterns, then use ${toolNamePrefix}read_file to examine the full context of interesting matches before using ${toolNamePrefix}replace_in_file to make informed changes.
-- When creating a new project (such as an app, website, or any software project), organize all new files within a dedicated project directory unless the user specifies otherwise. Use appropriate file paths when creating files, as the ${toolNamePrefix}write_to_file tool will automatically create any necessary directories. Structure the project logically, adhering to best practices for the specific type of project being created. Unless otherwise specified, new projects should be easily run without additional setup, for example most projects can be built in HTML, CSS, and JavaScript - which you can open in a browser.
-- Be sure to consider the type of project (e.g. Python, JavaScript, web application) when determining the appropriate structure and files to include. Also consider what files may be most relevant to accomplishing the task, for example looking at a project's manifest file would help you understand the project's dependencies, which you could incorporate into any code you write.
-- When making changes to code, always consider the context in which the code is being used. Ensure that your changes are compatible with the existing codebase and that they follow the project's coding standards and best practices.
-- **Adhere to any established coding style, linting rules, or naming conventions if they are known or can be inferred from the existing codebase, to maintain consistency.**
-- When you want to modify a file, use the ${toolNamePrefix}replace_in_file or ${toolNamePrefix}write_to_file tool directly with the desired changes. You do not need to display the changes before using the tool.
-- **Do not guess or hallucinate file content that has not been explicitly provided or read. Always read an existing file with \`${toolNamePrefix}read_file\` (or rely on content the user directly provided) before modifying it, unless you are creating a brand-new file.**
-- Do not ask for more information than necessary. Use the tools provided to accomplish the user's request efficiently and effectively. When you've completed your task, you must use the ${toolNamePrefix}attempt_completion tool to present the result to the user.
-- The user may provide a file's contents directly in their message, in which case you shouldn't use the ${toolNamePrefix}read_file tool to get the file contents again since you already have it.
-- Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
-- NEVER end ${toolNamePrefix}attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
-- You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.
-- When presented with images, utilize your vision capabilities to thoroughly examine them and extract meaningful information. Incorporate these insights into your thought process as you accomplish the user's task.
-- When using the ${toolNamePrefix}replace_in_file tool, you must include complete lines in your SEARCH blocks, not partial lines. The system requires exact line matches and cannot match partial lines. For example, if you want to match a line containing "const x = 5;", your SEARCH block must include the entire line, not just "x = 5" or other fragments.
-- When using the ${toolNamePrefix}replace_in_file tool, if you use multiple SEARCH/REPLACE blocks, list them in the order they appear in the file. For example if you need to make changes to both line 10 and line 50, first include the SEARCH/REPLACE block for line 10, followed by the SEARCH/REPLACE block for line 50.
-- It is critical you wait for the user's response after each tool use, in order to confirm the success of the tool use. For example, if asked to make a todo app, you would create a file, wait for the user's response it was created successfully, then create another file if needed, wait for the user's response it was created successfully, etc.
-- Keep the inline docs up to date if needed.
+- Work only with relative paths; you may \`cd\` into child directories but never use \`cd ..\`, root, or absolute paths.
+- When generating code, tests, or other comment-capable files, prepend a comment describing the file's purpose plus \u201Cgenerated by polka.codes\u201D.
+  For text files (e.g. README.md), append a footer with the same notice.
+- Never describe what changed inside code comments; comments must focus on purpose or usage only.
+- Before using ${toolNamePrefix}execute_command, consider SYSTEM INFORMATION to ensure commands suit the user's OS. If a command must run in a subdirectory, prepend a single \`cd childDir &&\` segment.
+- Use ${toolNamePrefix}search_files for broad analysis, then ${toolNamePrefix}read_file to inspect context, and finally ${toolNamePrefix}replace_in_file or ${toolNamePrefix}write_to_file to modify.
+- Prefer ${toolNamePrefix}replace_in_file for focused edits; choose ${toolNamePrefix}write_to_file for new files or complete rewrites.
+- When creating a new file, look for existing files with similar content or patterns; if found, read them and use their structure or conventions as a reference.
+- SEARCH blocks in ${toolNamePrefix}replace_in_file must match whole lines. If multiple blocks are needed, list them in file order.
+- Do not guess unseen content. Read existing files first unless creating new ones.
+- Follow existing style, lint, and naming conventions. Ensure all changes compile and pass tests where applicable.
+- ALWAYS wait for the user's confirmation after each tool call before starting the next step.
+- The agent must never invoke more than 5 tools in a single response.
+- Do not end ${toolNamePrefix}attempt_completion output with questions or conversational prompts.
+- Avoid filler words like \u201CGreat\u201D, \u201CCertainly\u201D, \u201COkay\u201D, \u201CSure\u201D at the start of responses; be direct and technical.
+- Keep inline documentation current as you edit.
 `;
 var objectives = (toolNamePrefix) => `
 ====
 
 OBJECTIVE
 
-You accomplish a given task iteratively, breaking it down into clear steps and working through them methodically.
+You solve the user's task by working in small, verifiable steps.
 
-1. Analyze the user's task and set clear, achievable goals to accomplish it. Prioritize these goals in a logical order.
-2. Work through these goals sequentially, utilizing available tools one at a time as necessary. Each goal should correspond to a distinct step in your problem-solving process. You will be informed on the work completed and what's remaining as you go.
-3. Remember, you have extensive capabilities with access to a wide range of tools that can be used in powerful and clever ways as necessary to accomplish each goal. Before calling a tool, do some analysis within <thinking></thinking> tags. First, analyze the file structure provided in environment_details to gain context and insights for proceeding effectively. Then, think about which of the provided tools is the most relevant tool to accomplish the user's task. Next, go through each of the required parameters of the relevant tool and determine if the user has directly provided or given enough information to infer a value. When deciding if the parameter can be inferred, carefully consider all the context to see if it supports a specific value. If all of the required parameters are present or can be reasonably inferred, close the thinking tag and proceed with the tool use.
-4. Once you've completed the user's task, you must use the ${toolNamePrefix}attempt_completion tool to present the result of the task to the user.
-5. The user may provide feedback, which you can use to make improvements and try again. But DO NOT continue in pointless back and forth conversations, i.e. don't end your responses with questions or offers for further assistance.`;
+1. **Plan** - Parse the task, list clear goals, and order them logically.
+2. **Think** - Wrap private reasoning in <thinking></thinking>.
+   \u2022 Review project context.
+   \u2022 Select the single best tool for the next goal.
+   \u2022 Ensure every required parameter is available or can be inferred.
+3. **Act** - Invoke one tool per step. Wait for the system's response (and user confirmation where required) before continuing.
+4. **Iterate** - Repeat Plan \u2192 Think \u2192 Act until all goals are complete.
+5. **Complete** - Use ${toolNamePrefix}attempt_completion to deliver the final result. Do not invite further discussion unless the user explicitly requests changes.
+`;
 var fullSystemPrompt4 = (info, tools, toolNamePrefix, instructions, scripts) => `
 ${basePrompt2}
 ${toolUsePrompt(tools, toolNamePrefix)}
@@ -3997,6 +4136,7 @@ export {
   generateGitCommitMessage,
   generateGithubPullRequestDetails,
   generateProjectConfig,
+  getArray,
   getAvailableTools,
   getBoolean,
   getInt,

package/package.json

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