dhalsim 0.1.0

package/dist/session/index.d.ts

@@ -0,0 +1,4 @@
+export type { CloseBrowserResult, ClosePageResult, NewPageResult, StartBrowserOptions, StartBrowserResult, } from "./manager";
+export { BrowserSessionManager, getSessionManager, resetSessionManager } from "./manager";
+export { TestBrowserSessionManager } from "./test-manager";
+export type { BrowserEntry, BrowserInfo, IBrowserSessionManager, PageEntry, PageInfo } from "./types";

package/dist/session/manager.d.ts

@@ -0,0 +1,59 @@
+import type { Page } from "playwright-core";
+import type { BrowserInfo, PageInfo } from "./types";
+type Logger = {
+    debug: (...args: unknown[]) => void;
+};
+export interface ProxyOptions {
+    server: string;
+    username?: string;
+    password?: string;
+}
+export interface StartBrowserOptions {
+    headless?: boolean;
+    url?: string;
+    /** Proxy server configuration */
+    proxy?: ProxyOptions;
+    /** Auto-detect timezone/locale from proxy IP */
+    geoip?: boolean;
+}
+export interface StartBrowserResult {
+    browserId: string;
+    pageId: string;
+    url: string;
+}
+export interface NewPageResult {
+    pageId: string;
+    browserId: string;
+    url: string;
+    title: string;
+}
+export interface CloseBrowserResult {
+    success: true;
+    closedPages: string[];
+}
+export interface ClosePageResult {
+    success: true;
+}
+export declare class BrowserSessionManager {
+    private browsers;
+    private pages;
+    private browserCounter;
+    private pageCounter;
+    private logger;
+    constructor(logger?: Logger);
+    private nextBrowserId;
+    private nextPageId;
+    startBrowser(options?: StartBrowserOptions): Promise<StartBrowserResult>;
+    closeBrowser(browserId: string): Promise<CloseBrowserResult>;
+    listBrowsers(): BrowserInfo[];
+    newPage(browserId: string, url?: string): Promise<NewPageResult>;
+    closePage(pageId: string): Promise<ClosePageResult>;
+    listPages(browserId?: string): PageInfo[];
+    getPage(pageId: string): Page | undefined;
+    requirePage(pageId: string): Page;
+    getBrowserIdForPage(pageId: string): string | undefined;
+    closeAll(): Promise<void>;
+}
+export declare function getSessionManager(): BrowserSessionManager;
+export declare function resetSessionManager(): void;
+export {};

package/dist/session/manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/test-manager.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Test-only browser session manager using vanilla playwright-core.
+ * This bypasses camoufox-js to avoid better-sqlite3 compatibility issues with Bun.
+ */
+import { type Page } from "playwright-core";
+import type { BrowserInfo, PageInfo } from "./types";
+import type { StartBrowserOptions, StartBrowserResult, NewPageResult, CloseBrowserResult, ClosePageResult } from "./manager";
+/**
+ * Browser session manager for tests using vanilla playwright-core (chromium).
+ * API-compatible with BrowserSessionManager.
+ */
+export declare class TestBrowserSessionManager {
+    private browsers;
+    private pages;
+    private browserCounter;
+    private pageCounter;
+    private nextBrowserId;
+    private nextPageId;
+    startBrowser(options?: StartBrowserOptions): Promise<StartBrowserResult>;
+    closeBrowser(browserId: string): Promise<CloseBrowserResult>;
+    listBrowsers(): BrowserInfo[];
+    newPage(browserId: string, url?: string): Promise<NewPageResult>;
+    closePage(pageId: string): Promise<ClosePageResult>;
+    listPages(browserId?: string): PageInfo[];
+    getPage(pageId: string): Page | undefined;
+    requirePage(pageId: string): Page;
+    getBrowserIdForPage(pageId: string): string | undefined;
+    /**
+     * Reset a page to clean state with HTML content or blank.
+     */
+    resetPage(pageId: string, html?: string): Promise<void>;
+    closeAll(): Promise<void>;
+}

package/dist/session/types.d.ts

@@ -0,0 +1,41 @@
+import type { Browser, BrowserContext, Page } from "playwright-core";
+export interface BrowserInfo {
+    id: string;
+    headless: boolean;
+    pageIds: string[];
+}
+export interface PageInfo {
+    id: string;
+    browserId: string;
+    url: string;
+    title: string;
+}
+export interface BrowserEntry {
+    browser: Browser;
+    context: BrowserContext;
+    headless: boolean;
+}
+export interface PageEntry {
+    page: Page;
+    browserId: string;
+}
+/**
+ * Interface for browser session managers.
+ * Both BrowserSessionManager and TestBrowserSessionManager implement this.
+ */
+export interface IBrowserSessionManager {
+    getPage(pageId: string): Page | undefined;
+    requirePage(pageId: string): Page;
+    getBrowserIdForPage(pageId: string): string | undefined;
+    listPages(browserId?: string): PageInfo[];
+    listBrowsers(): BrowserInfo[];
+    newPage(browserId: string, url?: string): Promise<{
+        pageId: string;
+        browserId: string;
+        url: string;
+        title: string;
+    }>;
+    closePage(pageId: string): Promise<{
+        success: true;
+    }>;
+}

package/dist/state/index.d.ts

@@ -0,0 +1 @@
+export { PageStateScanner, DEFAULT_CONFIG, type FormatConfig } from "./page-state";

package/dist/state/page-state.d.ts

@@ -0,0 +1,99 @@
+import type { IBrowserSessionManager } from "../session";
+export interface FormatConfig {
+    /** Max length for content summary (0 = no limit) */
+    maxContentLength: number;
+    /** Include DOM structure hints */
+    includeStructure: boolean;
+    /** Include content summary */
+    includeSummary: boolean;
+    /** Max number of links to show (0 = no limit). Default: 50 */
+    maxLinks: number;
+}
+export declare const DEFAULT_CONFIG: FormatConfig;
+/**
+ * Scans pages and formats state for LLM context injection.
+ */
+export declare class PageStateScanner {
+    private manager;
+    private config;
+    private cachedState;
+    private scanPromise;
+    constructor(manager: IBrowserSessionManager, config?: FormatConfig);
+    /**
+     * Get cached state synchronously (for trailing message).
+     * Call refreshState() to update the cache.
+     */
+    getCachedState(): string;
+    /**
+     * Refresh the cached state (call after state-changing operations).
+     * Uses proper locking to avoid concurrent scans and handles errors correctly.
+     */
+    refreshState(): Promise<void>;
+    private doRefresh;
+    /**
+     * Scan all open pages and format as compact string for trailing message.
+     * Output is wrapped in <CurrentBrowserState> tags for clear LLM context.
+     */
+    scanAllPages(): Promise<string>;
+    /**
+     * Scan a single page for state.
+     */
+    private scanPage;
+    /**
+     * Get all data-test attribute values from the page.
+     */
+    private getDataAttributes;
+    /**
+     * Get visible text content from page.
+     */
+    private getContentSummary;
+    /**
+     * Get simplified DOM structure (forms, main sections).
+     */
+    private getStructure;
+    /**
+     * Get all interactive elements.
+     * Processes all selector types in parallel for better performance.
+     */
+    private getInteractiveElements;
+    /**
+     * Extract info from a single element.
+     */
+    private extractElementInfo;
+    /**
+     * Format elements with unique indexed selectors when duplicates exist.
+     * Returns array of formatted lines.
+     */
+    private formatElements;
+    /**
+     * Format page state as compact string.
+     */
+    private formatPageState;
+    /**
+     * Check if an ID looks like garbage (dynamically generated).
+     */
+    private isGarbageId;
+    /**
+     * Check if a class name is meaningful (not framework garbage).
+     */
+    private isMeaningfulClass;
+    /**
+     * Escape special characters for CSS selector.
+     */
+    private escapeCSSSelector;
+    /**
+     * Scan for collapsed sections (accordions, panels) and extract their contents.
+     * This allows the agent to see what options are available BEFORE expanding.
+     */
+    private getCollapsedSections;
+    /**
+     * Get all <select> elements with their available options.
+     * This allows the agent to see dropdown options BEFORE opening them.
+     */
+    private getSelectOptions;
+    /**
+     * Get a valid CSS selector for element type when no better selector is available.
+     * Maps our internal type names to actual valid CSS selectors.
+     */
+    private getFallbackSelector;
+}

package/dist/state/page-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stealth.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Human-like timing utilities for browser automation.
+ */
+/**
+ * Generate a random delay within a range (for human-like timing).
+ * @param min Minimum delay in milliseconds
+ * @param max Maximum delay in milliseconds
+ */
+export declare function randomDelay(min: number, max: number): number;
+/**
+ * Sleep for a random duration (for human-like timing).
+ * @param min Minimum delay in milliseconds
+ * @param max Maximum delay in milliseconds
+ */
+export declare function humanDelay(min?: number, max?: number): Promise<void>;

package/dist/subagents/dhalsim.d.ts

@@ -0,0 +1,112 @@
+import { z } from "llmist";
+import type { ExecutionContext, GadgetMediaOutput } from "llmist";
+import type { IBrowserSessionManager, StartBrowserOptions, StartBrowserResult } from "../session";
+/**
+ * Session manager type with the required methods for browser automation.
+ * Compatible with both BrowserSessionManager and TestBrowserSessionManager.
+ */
+export type DhalsimSessionManager = IBrowserSessionManager & {
+    startBrowser(options: StartBrowserOptions): Promise<StartBrowserResult>;
+    closeAll(): Promise<void>;
+};
+/**
+ * Options for configuring the Dhalsim subagent.
+ */
+export interface DhalsimOptions {
+    /** Custom session manager for Node.js compatibility or testing */
+    sessionManager?: DhalsimSessionManager;
+    /** Custom system prompt (defaults to DHALSIM_SYSTEM_PROMPT) */
+    systemPrompt?: string;
+}
+declare const Dhalsim_base: new () => {
+    description: string;
+    parameterSchema: z.ZodObject<{
+        task: z.ZodString;
+        url: z.ZodString;
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        model: z.ZodOptional<z.ZodString>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    name: string | undefined;
+    timeoutMs: number | undefined;
+    examples: import("llmist").GadgetExample<{
+        task: string;
+        url: string;
+        maxIterations?: number | undefined;
+        model?: string | undefined;
+        headless?: boolean | undefined;
+    }>[] | undefined;
+    readonly params: {
+        task: string;
+        url: string;
+        maxIterations?: number | undefined;
+        model?: string | undefined;
+        headless?: boolean | undefined;
+    };
+    execute(params: Record<string, unknown>, ctx?: ExecutionContext): import("llmist").GadgetExecuteReturn | Promise<import("llmist").GadgetExecuteReturn>;
+    throwIfAborted(ctx?: ExecutionContext): void;
+    onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
+    createLinkedAbortController(ctx?: ExecutionContext): AbortController;
+    readonly instruction: string;
+    getInstruction(optionsOrArgPrefix?: string | {
+        argPrefix?: string;
+        startPrefix?: string;
+        endPrefix?: string;
+    }): string;
+} & {
+    params: {
+        task: string;
+        url: string;
+        maxIterations?: number | undefined;
+        model?: string | undefined;
+        headless?: boolean | undefined;
+    };
+};
+/**
+ * Dhalsim subagent - a high-level gadget that runs its own agent loop
+ * to accomplish web browsing tasks autonomously.
+ *
+ * This is the recommended way for most users to interact with dhalsim.
+ * Instead of registering 26+ individual gadgets, just use Dhalsim
+ * and let it handle the complexity of web automation.
+ *
+ * @example
+ * ```typescript
+ * // In your agent
+ * const dhalsim = new Dhalsim();
+ * registry.register('Dhalsim', dhalsim);
+ *
+ * // The agent can now call:
+ * // Dhalsim(task="Find the price of iPhone 16 Pro", url="https://apple.com")
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom session manager for Node.js compatibility
+ * import { TestBrowserSessionManager } from "dhalsim";
+ *
+ * const dhalsim = new Dhalsim({
+ *   sessionManager: new TestBrowserSessionManager(),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With minimal prompt for simpler tasks
+ * import { DHALSIM_MINIMAL_PROMPT } from "dhalsim";
+ *
+ * const dhalsim = new Dhalsim({
+ *   systemPrompt: DHALSIM_MINIMAL_PROMPT,
+ * });
+ * ```
+ */
+export declare class Dhalsim extends Dhalsim_base {
+    private customSessionManager?;
+    private customSystemPrompt?;
+    constructor(options?: DhalsimOptions);
+    execute(params: this["params"], ctx?: ExecutionContext): Promise<{
+        result: string;
+        media?: GadgetMediaOutput[];
+    }>;
+}
+export {};

package/dist/subagents/dhalsim.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/subagents/index.d.ts

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

package/dist/subagents/prompts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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\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.";
+/**
+ * Truncated prompt for simpler tasks (fewer gadgets, less context).
+ */
+export declare const DHALSIM_MINIMAL_PROMPT = "You are a browser agent. Complete the given task efficiently.\n\n## Browser State\n<CurrentBrowserState> shows what's on screen:\n- OPEN PAGES: Your page is \"p1\"\n- Selectors for INPUTS, BUTTONS, LINKS\n\n## Rules\n1. Use Navigate(pageId=\"p1\", url=\"...\") to visit URLs\n2. Use selectors exactly as shown in <CurrentBrowserState>\n3. Use DismissOverlays for cookie banners\n4. Complete the task and report findings";

package/dist/utils/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Centralized constants for the dhalsim browser automation CLI.
+ */
+export declare const ELEMENT_TEXT_MAX_LENGTH = 100;
+export declare const ERROR_PREVIEW_LENGTH = 57;
+export declare const RESULT_PREVIEW_LENGTH = 97;
+export declare const TOOL_NAME_MAX_LENGTH = 27;
+export declare const DEFAULT_CLICK_TIMEOUT = 5000;
+export declare const DEFAULT_NAVIGATION_TIMEOUT = 30000;
+export declare const OVERLAY_DISMISS_DELAY = 300;
+export declare const UI_SETTLE_DELAY = 150;
+export declare const BUTTON_SCORING: {
+    readonly saturationWeight: 5;
+    readonly brightnessThreshold: 100;
+    readonly positionWeight: 2;
+    readonly indexDecay: 0.5;
+    readonly areaDivisor: 5000;
+};
+export declare const MAX_SELECTORS_PER_QUERY = 50;
+export declare const MAX_INPUTS_TO_SCAN = 100;

package/dist/utils/element-checks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Utility functions for element existence checking.
+ */
+import type { Locator } from "playwright-core";
+/**
+ * Checks if an element exists and returns an error JSON string if not found or ambiguous.
+ * Returns null if exactly one element matches.
+ *
+ * When multiple elements match, provides disambiguation hints to help select a specific element.
+ */
+export declare function checkElementExists(locator: Locator, selector: string): Promise<string | null>;
+/**
+ * Checks if an element exists and is visible.
+ * Returns an error JSON string if not found, ambiguous, or not visible.
+ * Returns null if exactly one element matches and is visible.
+ */
+export declare function checkElementVisible(locator: Locator, selector: string): Promise<string | null>;

package/dist/utils/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for error handling and text processing.
+ */
+/**
+ * Extracts a string message from an unknown error type.
+ * Safely handles both Error objects and other thrown values.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Truncates text to a maximum length, adding ellipsis if truncated.
+ */
+export declare function truncate(text: string, maxLength: number): string;

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Utility exports for dhalsim browser automation CLI.
+ */
+export { getErrorMessage, truncate, humanDelay, randomDelay } from "llmist";
+export { ELEMENT_TEXT_MAX_LENGTH, ERROR_PREVIEW_LENGTH, RESULT_PREVIEW_LENGTH, TOOL_NAME_MAX_LENGTH, DEFAULT_CLICK_TIMEOUT, DEFAULT_NAVIGATION_TIMEOUT, OVERLAY_DISMISS_DELAY, BUTTON_SCORING, MAX_SELECTORS_PER_QUERY, MAX_INPUTS_TO_SCAN, } from "./constants.js";
+export { checkElementExists, checkElementVisible } from "./element-checks.js";

package/package.json

@@ -0,0 +1,88 @@
+{
+	"name": "dhalsim",
+	"version": "0.1.0",
+	"description": "Browser automation for llmist agents using Camoufox anti-detect browser",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"llmist": {
+		"gadgets": "./dist/index.js",
+		"factory": "./dist/index.js",
+		"subagents": {
+			"BrowseWeb": {
+				"entryPoint": "./dist/index.js",
+				"export": "Dhalsim",
+				"description": "Browse websites and accomplish tasks autonomously",
+				"uses": ["Navigate", "Click", "Screenshot", "GetFullPageContent", "Fill"],
+				"defaultModel": "sonnet",
+				"maxIterations": 15
+			}
+		},
+		"presets": {
+			"all": "*",
+			"subagent": ["BrowseWeb"],
+			"readonly": ["Navigate", "Screenshot", "GetFullPageContent", "ListPages"],
+			"minimal": ["Navigate", "Screenshot", "GetFullPageContent"]
+		},
+		"session": {
+			"factory": "getSessionManager",
+			"type": "browser"
+		}
+	},
+	"scripts": {
+		"build": "bun build src/index.ts --outdir dist --target node --external playwright-core --external camoufox-js --external chromium-bidi --external electron --external llmist && bun run build:types",
+		"build:types": "tsc --emitDeclarationOnly",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint .",
+		"format": "biome format --write .",
+		"check": "biome check --write .",
+		"test": "vitest run --no-file-parallelism",
+		"precheck": "bun run lint && bun run typecheck && bun run test",
+		"prepare": "lefthook install"
+	},
+	"keywords": [
+		"browser",
+		"automation",
+		"playwright",
+		"llm",
+		"agent",
+		"web",
+		"scraping"
+	],
+	"author": "Zbigniew Sobiecki",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zbigniewsobiecki/dhalsim.git"
+	},
+	"homepage": "https://github.com/zbigniewsobiecki/dhalsim#readme",
+	"bugs": {
+		"url": "https://github.com/zbigniewsobiecki/dhalsim/issues"
+	},
+	"files": [
+		"dist",
+		"dhalsim-icon.png",
+		"LICENSE",
+		"README.md"
+	],
+	"dependencies": {
+		"camoufox-js": "github:zbigniewsobiecki/camoufox-js#impit-fallback",
+		"sharp": "^0.34.5"
+	},
+	"optionalDependencies": {
+		"better-sqlite3": "^11.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.2",
+		"@llmist/testing": ">=9.2.0",
+		"@types/node": "^20.12.7",
+		"bun-types": "^1.3.2",
+		"lefthook": "^1.6.0",
+		"llmist": ">=9.2.0",
+		"typescript": "^5.4.5",
+		"vitest": "^4.0.15"
+	},
+	"peerDependencies": {
+		"llmist": ">=9.2.0"
+	}
+}