dhalsim 1.6.1 → 1.7.0

package/dist/gadgets/index.d.ts

@@ -9,4 +9,5 @@ export { GoBack, GoForward, Navigate, Reload } from "./navigation";
 export { ClosePage, ListPages, NewPage } from "./page";
 export { ExecuteScript } from "./script";
 export { Wait, WaitForElement } from "./wait";
-export { RequestUserAssistance } from "./user-input";
+export { RequestUserAssistance, USER_ASSISTANCE_REASONS } from "./user-input";
+export type { UserAssistanceReason } from "./user-input";

package/dist/gadgets/user-input.d.ts

@@ -1,5 +1,7 @@
 import { z } from "llmist";
 import type { IBrowserSessionManager } from "../session";
+export declare const USER_ASSISTANCE_REASONS: readonly ["captcha", "2fa_code", "sms_code", "manual_action", "confirmation", "other"];
+export type UserAssistanceReason = (typeof USER_ASSISTANCE_REASONS)[number];
 declare const RequestUserAssistance_base: new () => {
     description: string;
     parameterSchema: z.ZodObject<{

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export declare const VERSION = "1.2.0";
 export { BrowserSessionManager, getSessionManager, TestBrowserSessionManager } from "./session";
 export type { IBrowserSessionManager } from "./session";
 export { createDhalsimGadgets, createGadgetsByPreset, createGadgetsByName, type DhalsimConfig, type DhalsimGadgets, type DhalsimPreset, } from "./factory";
-export { Dhalsim, DHALSIM_SYSTEM_PROMPT, DHALSIM_MINIMAL_PROMPT } from "./subagents";
-export type { DhalsimOptions, DhalsimSessionManager } from "./subagents";
+export { Dhalsim, DHALSIM_SYSTEM_PROMPT, DHALSIM_MINIMAL_PROMPT, createDhalsimSystemPrompt, } from "./subagents";
+export type { DhalsimOptions, DhalsimSessionManager, UserAssistanceParams, UserAssistanceCallback, } from "./subagents";
+export type { UserAssistanceReason } from "./gadgets/user-input";
+export { USER_ASSISTANCE_REASONS } from "./gadgets/user-input";

package/dist/index.js

@@ -15362,11 +15362,19 @@ return items.length;`
 
 // src/gadgets/user-input.ts
 import { Gadget as Gadget11, z as z12, HumanInputRequiredException } from "llmist";
+var USER_ASSISTANCE_REASONS = [
+  "captcha",
+  "2fa_code",
+  "sms_code",
+  "manual_action",
+  "confirmation",
+  "other"
+];
 
 class RequestUserAssistance extends Gadget11({
   description: "Requests input or confirmation from the user. Use when encountering captchas, 2FA codes, or other challenges requiring human intervention. The browser should be in headed mode (headless=false) if user needs to interact with it.",
   schema: z12.object({
-    reason: z12.enum(["captcha", "2fa_code", "sms_code", "manual_action", "confirmation", "other"]).describe("Type of assistance needed"),
+    reason: z12.enum(USER_ASSISTANCE_REASONS).describe("Type of assistance needed"),
     message: z12.string().describe("Message to display to the user explaining what's needed")
   }),
   examples: [
@@ -16078,7 +16086,38 @@ ${states.join(`
   }
 }
 // src/subagents/prompts.ts
-var DHALSIM_SYSTEM_PROMPT = `You are a browser automation agent focused on completing a specific web task.
+var GADGET_LIST_WITH_USER_ASSISTANCE = `## Available Gadgets
+- ReportResult: **REQUIRED** - Call this to return your findings when task is complete
+- Navigate: Go to a URL
+- Click: Click an element (auto-waits for element to be actionable)
+- Fill: Fill a form input
+- FillForm: Fill multiple fields and submit
+- Select: Select dropdown option
+- Check: Toggle checkboxes
+- GetFullPageContent: Read page text content
+- Screenshot: Capture the page (use when you need to show visual results)
+- DismissOverlays: Auto-dismiss cookie banners
+- Scroll: Scroll the page
+- WaitForElement: Wait for an element to appear
+- Wait: General wait
+- RequestUserAssistance: Ask user for help with CAPTCHAs, 2FA codes, or other human-only challenges`;
+var GADGET_LIST_WITHOUT_USER_ASSISTANCE = `## Available Gadgets
+- ReportResult: **REQUIRED** - Call this to return your findings when task is complete
+- Navigate: Go to a URL
+- Click: Click an element (auto-waits for element to be actionable)
+- Fill: Fill a form input
+- FillForm: Fill multiple fields and submit
+- Select: Select dropdown option
+- Check: Toggle checkboxes
+- GetFullPageContent: Read page text content
+- Screenshot: Capture the page (use when you need to show visual results)
+- DismissOverlays: Auto-dismiss cookie banners
+- Scroll: Scroll the page
+- WaitForElement: Wait for an element to appear
+- Wait: General wait`;
+function createDhalsimSystemPrompt(options) {
+  const gadgetList = options.includeUserAssistance ? GADGET_LIST_WITH_USER_ASSISTANCE : GADGET_LIST_WITHOUT_USER_ASSISTANCE;
+  return `You are a browser automation agent focused on completing a specific web task.
 
 ## Browser State (<CurrentBrowserState>)
 After each message, you receive a <CurrentBrowserState> block showing the LIVE browser state.
@@ -16118,21 +16157,7 @@ If an action doesn't produce the expected result after 2-3 attempts:
 3. Try a different approach or skip and continue
 NEVER click the same element more than 3 times in a row.
 
-## Available Gadgets
-- ReportResult: **REQUIRED** - Call this to return your findings when task is complete
-- Navigate: Go to a URL
-- Click: Click an element (auto-waits for element to be actionable)
-- Fill: Fill a form input
-- FillForm: Fill multiple fields and submit
-- Select: Select dropdown option
-- Check: Toggle checkboxes
-- GetFullPageContent: Read page text content
-- Screenshot: Capture the page (use when you need to show visual results)
-- DismissOverlays: Auto-dismiss cookie banners
-- Scroll: Scroll the page
-- WaitForElement: Wait for an element to appear
-- Wait: General wait
-- RequestUserAssistance: Ask user for help with CAPTCHAs, 2FA codes, or other human-only challenges
+${gadgetList}
 
 ## Task Completion
 When you have accomplished the task, you MUST call ReportResult with your findings:
@@ -16141,6 +16166,10 @@ When you have accomplished the task, you MUST call ReportResult with your findin
 3. If you took screenshots, describe what they show in the result
 
 Remember: You are a focused automation agent. Complete the task, call ReportResult, then stop.`;
+}
+var DHALSIM_SYSTEM_PROMPT = createDhalsimSystemPrompt({
+  includeUserAssistance: true
+});
 var DHALSIM_MINIMAL_PROMPT = `You are a browser agent. Complete the given task efficiently.
 
 ## Browser State
@@ -16189,10 +16218,14 @@ Use this for web research, data extraction, form filling, or any web-based task.
 }) {
   customSessionManager;
   customSystemPrompt;
+  userAssistanceEnabled;
+  customUserAssistanceCallback;
   constructor(options) {
     super();
     this.customSessionManager = options?.sessionManager;
     this.customSystemPrompt = options?.systemPrompt;
+    this.userAssistanceEnabled = options?.userAssistance;
+    this.customUserAssistanceCallback = options?.onUserAssistance;
     if (options?.timeoutMs !== undefined) {
       this.timeoutMs = options.timeoutMs === 0 ? undefined : options.timeoutMs;
     }
@@ -16222,6 +16255,8 @@ Use this for web research, data extraction, form filling, or any web-based task.
       subagentKey: "navigationTimeoutMs",
       defaultValue: 60000
     });
+    const userAssistanceEnabled = this.userAssistanceEnabled ?? (this.customUserAssistanceCallback !== undefined || ctx?.requestHumanInput !== undefined);
+    logger13?.debug(`[BrowseWeb] User assistance enabled=${userAssistanceEnabled}`);
     const collectedMedia = [];
     const manager = this.customSessionManager ?? new BrowserSessionManager(logger13);
     const isOwnedManager = !this.customSessionManager;
@@ -16275,11 +16310,12 @@ Use this for web research, data extraction, form filling, or any web-based task.
         new Scroll(manager),
         new WaitForElement(manager),
         new Wait(manager),
-        new RequestUserAssistance(manager)
+        ...userAssistanceEnabled ? [new RequestUserAssistance(manager)] : []
       ];
       const { AgentBuilder, LLMist } = getHostExports(ctx);
       const client = new LLMist;
-      const builder = new AgentBuilder(client).withModel(model).withSystem(this.customSystemPrompt ?? DHALSIM_SYSTEM_PROMPT).withMaxIterations(maxIterations).withGadgets(...gadgets).withTrailingMessage((trailingCtx) => [
+      const systemPrompt = this.customSystemPrompt ?? createDhalsimSystemPrompt({ includeUserAssistance: userAssistanceEnabled });
+      const builder = new AgentBuilder(client).withModel(model).withSystem(systemPrompt).withMaxIterations(maxIterations).withGadgets(...gadgets).withTrailingMessage((trailingCtx) => [
         pageStateScanner.getCachedState(),
         "",
         `[Iteration ${trailingCtx.iteration + 1}/${trailingCtx.maxIterations}]`,
@@ -16294,8 +16330,23 @@ Use this for web research, data extraction, form filling, or any web-based task.
       });
       if (ctx) {
         builder.withParentContext(ctx);
-        if (ctx.requestHumanInput) {
-          builder.onHumanInput(ctx.requestHumanInput);
+        if (userAssistanceEnabled) {
+          if (this.customUserAssistanceCallback) {
+            builder.onHumanInput(async (prompt) => {
+              const match = prompt.match(/^\[([A-Z0-9_]+)\]\s*(.*)$/s);
+              if (match) {
+                const reason = match[1].toLowerCase();
+                const message = match[2];
+                return this.customUserAssistanceCallback({ reason, message });
+              }
+              return this.customUserAssistanceCallback({
+                reason: "other",
+                message: prompt
+              });
+            });
+          } else if (ctx.requestHumanInput) {
+            builder.onHumanInput(ctx.requestHumanInput);
+          }
         }
       }
       if (dismissResult !== null) {
@@ -16345,8 +16396,10 @@ export {
   getSessionManager,
   createGadgetsByPreset,
   createGadgetsByName,
+  createDhalsimSystemPrompt,
   createDhalsimGadgets,
   VERSION,
+  USER_ASSISTANCE_REASONS,
   TestBrowserSessionManager,
   Dhalsim,
   DHALSIM_SYSTEM_PROMPT,

package/dist/subagents/dhalsim.d.ts

@@ -1,6 +1,7 @@
 import { z } from "llmist";
 import type { ExecutionContext, GadgetMediaOutput } from "llmist";
 import type { IBrowserSessionManager, StartBrowserOptions, StartBrowserResult } from "../session";
+import { type UserAssistanceReason } from "../gadgets";
 /**
  * Session manager type with the required methods for browser automation.
  * Compatible with both BrowserSessionManager and TestBrowserSessionManager.
@@ -9,6 +10,20 @@ export type DhalsimSessionManager = IBrowserSessionManager & {
     startBrowser(options: StartBrowserOptions): Promise<StartBrowserResult>;
     closeAll(): Promise<void>;
 };
+/**
+ * Parameters passed to the custom user assistance callback.
+ */
+export interface UserAssistanceParams {
+    /** Type of assistance needed */
+    reason: UserAssistanceReason;
+    /** Message describing what's needed */
+    message: string;
+}
+/**
+ * Custom callback for handling user assistance requests.
+ * Return the user's response (e.g., 2FA code, "done" for captchas).
+ */
+export type UserAssistanceCallback = (params: UserAssistanceParams) => Promise<string>;
 /**
  * Options for configuring the Dhalsim subagent.
  */
@@ -19,6 +34,21 @@ export interface DhalsimOptions {
     systemPrompt?: string;
     /** Overall timeout in milliseconds (default: 300000 = 5 min, 0 = disabled) */
     timeoutMs?: number;
+    /**
+     * Enable or disable RequestUserAssistance gadget.
+     * - true: Always include the gadget
+     * - false: Never include the gadget (agent won't know it exists)
+     * - undefined (default): Auto-detect based on callback availability
+     */
+    userAssistance?: boolean;
+    /**
+     * Custom callback for handling user assistance requests.
+     * When provided, this receives structured params instead of the raw message.
+     * The callback's return value is passed back to the agent.
+     *
+     * If not provided but userAssistance is enabled, falls back to ctx.requestHumanInput.
+     */
+    onUserAssistance?: UserAssistanceCallback;
 }
 declare const Dhalsim_base: new () => {
     description: string;
@@ -117,6 +147,8 @@ declare const Dhalsim_base: new () => {
 export declare class Dhalsim extends Dhalsim_base {
     private customSessionManager?;
     private customSystemPrompt?;
+    private userAssistanceEnabled?;
+    private customUserAssistanceCallback?;
     constructor(options?: DhalsimOptions);
     execute(params: this["params"], ctx?: ExecutionContext): Promise<{
         result: string;

package/dist/subagents/index.d.ts

@@ -1,3 +1,3 @@
 export { Dhalsim } from "./dhalsim";
-export type { DhalsimOptions, DhalsimSessionManager } from "./dhalsim";
-export { DHALSIM_SYSTEM_PROMPT, DHALSIM_MINIMAL_PROMPT } from "./prompts";
+export type { DhalsimOptions, DhalsimSessionManager, UserAssistanceParams, UserAssistanceCallback, } from "./dhalsim";
+export { DHALSIM_SYSTEM_PROMPT, DHALSIM_MINIMAL_PROMPT, createDhalsimSystemPrompt, } from "./prompts";

package/dist/subagents/prompts.d.ts

@@ -1,8 +1,14 @@
+/**
+ * Creates a system prompt with optional RequestUserAssistance gadget mention.
+ */
+export declare function createDhalsimSystemPrompt(options: {
+    includeUserAssistance: boolean;
+}): string;
 /**
  * System prompt for the Dhalsim subagent.
  * This is a focused version of the CLI prompt, optimized for task completion.
  */
-export declare const DHALSIM_SYSTEM_PROMPT = "You are a browser automation agent focused on completing a specific web task.\n\n## Browser State (<CurrentBrowserState>)\nAfter each message, you receive a <CurrentBrowserState> block showing the LIVE browser state.\nThis is your source of truth for what's on screen. It contains:\n- OPEN PAGES: List of available pageIds (e.g., \"p1\")\n- URL and title of each page\n- INPUTS: Form fields with CSS selectors\n- BUTTONS: Clickable buttons with CSS selectors\n- LINKS: Navigation links with CSS selectors\n- CHECKBOXES: Checkbox/radio inputs\n- MENUITEMS: Dropdown options (only visible when dropdown is open)\n\n## CRITICAL Rules\n1. You have ONE page (p1) already open. Use Navigate to go to URLs.\n2. ONLY use selectors exactly as shown in <CurrentBrowserState>\n3. NEVER guess selectors - use GetFullPageContent if you need more info\n4. Focus on completing the task efficiently - avoid unnecessary actions\n5. If a selector matches multiple elements, you'll get an error with a \"suggestions\" array containing valid selectors. USE ONE OF THESE SUGGESTIONS DIRECTLY - don't guess or modify them.\n6. For batch extraction: GetFullPageContent returns ALL matches when a selector matches multiple elements (as \"texts\" array). Use this instead of querying each element separately.\n\n## Efficient Pattern\nOn first call: Navigate and DismissOverlays are ALREADY done. Take action immediately.\nAfter any Navigate call: DismissOverlays, then interact with elements.\n\nIf an action doesn't produce expected results, use GetFullPageContent to diagnose before retrying.\n\n## Dropdown/Toggle Behavior\nDropdowns are TOGGLES - clicking the same trigger twice will close it!\n- After Click on a dropdown trigger, check <CurrentBrowserState> for MENUITEMS\n- If menuitems appear, click the menuitem ONCE - do NOT click the trigger again\n- One click opens, second click closes\n\n## Avoid Infinite Loops\nIf an action doesn't produce the expected result after 2-3 attempts:\n1. Stop retrying the same action\n2. Use GetFullPageContent or Screenshot to diagnose\n3. Try a different approach or skip and continue\nNEVER click the same element more than 3 times in a row.\n\n## Available Gadgets\n- ReportResult: **REQUIRED** - Call this to return your findings when task is complete\n- Navigate: Go to a URL\n- Click: Click an element (auto-waits for element to be actionable)\n- Fill: Fill a form input\n- FillForm: Fill multiple fields and submit\n- Select: Select dropdown option\n- Check: Toggle checkboxes\n- GetFullPageContent: Read page text content\n- Screenshot: Capture the page (use when you need to show visual results)\n- DismissOverlays: Auto-dismiss cookie banners\n- Scroll: Scroll the page\n- WaitForElement: Wait for an element to appear\n- Wait: General wait\n- RequestUserAssistance: Ask user for help with CAPTCHAs, 2FA codes, or other human-only challenges\n\n## Task Completion\nWhen you have accomplished the task, you MUST call ReportResult with your findings:\n1. Call ReportResult(result=\"...\") with all extracted data and findings\n2. Include any relevant URLs, text content, or structured data\n3. If you took screenshots, describe what they show in the result\n\nRemember: You are a focused automation agent. Complete the task, call ReportResult, then stop.";
+export declare const DHALSIM_SYSTEM_PROMPT: string;
 /**
  * Truncated prompt for simpler tasks (fewer gadgets, less context).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dhalsim",
-	"version": "1.6.1",
+	"version": "1.7.0",
 	"description": "Browser automation for llmist agents using Camoufox anti-detect browser",
 	"type": "module",
 	"main": "dist/index.js",