@hira-core/sdk 1.0.6 → 1.0.8

package/README.md

@@ -188,17 +188,22 @@ const utils = new BrowserUtils(context);
 
 #### Navigation & Interaction
 
-| Method                                     | Description                   |
-| ------------------------------------------ | ----------------------------- |
-| `utils.goto(url)`                          | Navigate to URL               |
-| `utils.click(selector)`                    | Wait + scroll + click         |
-| `utils.type(selector, text)`               | Wait + clear + type           |
-| `utils.getText(selector)`                  | Get text content              |
-| `utils.exists(selector, timeout?)`         | Check element exists          |
-| `utils.waitForElement(selector, timeout?)` | Wait for element              |
-| `utils.waitForNavigation()`                | Wait for page navigation      |
-| `utils.screenshot(path?)`                  | Take screenshot               |
-| `utils.sleep(ms)`                          | Delay (respects abort signal) |
+| Method                                     | Description                            |
+| ------------------------------------------ | -------------------------------------- |
+| `utils.goto(url)`                          | Navigate to URL                        |
+| `utils.click(selector)`                    | Wait + scroll + click                  |
+| `utils.click({ x, y })`                    | Click at specific coordinates          |
+| `utils.type(selector, text)`               | Wait + clear + type                    |
+| `utils.select(selector, value)`            | Select dropdown option (native `<select>`) |
+| `utils.getText(selector)`                  | Get text content                       |
+| `utils.getPosition(selector)`              | Get element center coordinates         |
+| `utils.exists(selector, timeout?)`         | Check element exists                   |
+| `utils.waitForElement(selector, timeout?)` | Wait for element                       |
+| `utils.waitForNavigation()`                | Wait for page navigation               |
+| `utils.screenshot(path?)`                  | Take screenshot                        |
+| `utils.sleep(ms)`                          | Delay (respects abort signal)          |
+| `utils.scroll({ deltaY })`                 | Smooth 60fps scroll (ease-in-out)      |
+| `utils.scroll({ deltaY, container })`      | Smooth scroll inside overflow container|
 
 #### Tab Management
 
@@ -344,6 +349,22 @@ npx @hira-core/cli build
 
 ---
 
+## Virtual Cursor
+
+The SDK includes a **virtual cursor** — a visible SVG cursor overlay that shows mouse movement, clicks, and scrolling in real-time. This is enabled by default and can be toggled via `IExecutionConfig.virtualCursor`:
+
+```typescript
+// In flow runner params
+execution: {
+  virtualCursor: true,   // default — show cursor overlay
+  // virtualCursor: false,  // disable cursor overlay
+}
+```
+
+When enabled, `BrowserUtils.click()`, `scroll()`, and other interaction methods will show realistic Bézier curve mouse movement powered by [ghost-cursor](https://github.com/nicr9/ghost-cursor).
+
+---
+
 ## License
 
 ISC

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _packages_shared from '@packages/shared';
 import { ProfileOutputValue, IWorkerLogMessage, ProfileStatus, IWorkerOutputMessage } from '@packages/shared';
-import * as puppeteer from 'puppeteer-core';
+import * as puppeteer_core from 'puppeteer-core';
 import { Browser, Page, Frame, ElementHandle } from 'puppeteer-core';
 import { EventEmitter } from 'events';
 
@@ -237,6 +237,12 @@ interface IExecutionConfig {
      * Dev mode: dùng constructor `super(AntidetectProvider.GPM, ...)` trong flow class.
      */
     antidetectProvider?: 'gpm' | 'hidemium' | 'genlogin' | 'adspower';
+    /**
+     * Enable virtual cursor — SVG arrow with Bézier curve mouse movement.
+     * When true, click() and type() will move cursor naturally before interacting.
+     * Default: true
+     */
+    virtualCursor?: boolean;
 }
 interface IBrowserWindowConfig {
     width: number;
@@ -314,6 +320,8 @@ interface IScriptContext<TConfig extends IFlowConfig = IFlowConfig> {
     page: Page;
     profile: IAntidetectProfile;
     index: number;
+    /** Execution config — includes virtualCursor flag etc. */
+    execution: IExecutionConfig;
     globalInput: InferGlobalInput<TConfig>;
     profileInput: InferProfileInput<TConfig>;
     /**
@@ -521,8 +529,8 @@ declare class GpmStandaloneAdapter implements IBrowserAdapter {
     constructor(logger: ILogger);
     private getBoundLogger;
     open(profileName: string, index: number, windowConfig: IBrowserWindowConfig): Promise<{
-        browser: puppeteer.Browser;
-        page: puppeteer.Page;
+        browser: puppeteer_core.Browser;
+        page: puppeteer_core.Page;
         profile: IAntidetectProfile;
     }>;
     close(profileId: string): Promise<void>;
@@ -595,8 +603,8 @@ declare class HidemiumStandaloneAdapter implements IBrowserAdapter {
     constructor(logger: ILogger);
     private getBoundLogger;
     open(profileName: string, index: number, windowConfig: IBrowserWindowConfig): Promise<{
-        browser: puppeteer.Browser;
-        page: puppeteer.Page;
+        browser: puppeteer_core.Browser;
+        page: puppeteer_core.Page;
         profile: IAntidetectProfile;
     }>;
     close(profileId: string): Promise<void>;
@@ -606,72 +614,505 @@ declare class HidemiumStandaloneAdapter implements IBrowserAdapter {
 declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     private ctx;
     private logger;
-    /** Output definitions từ flow config — dùng để validate writeOutput key */
+    /** Output definitions from flow config — used to validate writeOutput keys */
     private readonly outputDefs;
-    /** Set chứa các key hợp lệ — build 1 lần từ outputDefs */
+    /** Valid output keys set — built once from outputDefs */
     private readonly validOutputKeys;
+    /** The initial page when flow starts — activeDefault() returns here */
+    private readonly defaultPage;
+    /** The currently active page all methods operate on — changed via activeTab() */
+    private activePage;
+    /** Currently active iframe — null means main frame. Changed via activeIframe() */
+    private activeFrame;
+    /** Virtual cursor — Bézier movement + SVG visualization */
+    private readonly hiraCursor;
     constructor(context: IScriptContext<TConfig>);
+    /**
+     * CDP trick — Chromium thinks tab is always focused, not throttled
+     * when user switches to another tab or clicks elsewhere.
+     */
+    private enableFocusEmulation;
+    /**
+     * Apply stealth scripts to remove automation fingerprints.
+     * Uses evaluateOnNewDocument — runs BEFORE any page scripts on every navigation.
+     * Persists across navigations on the same page instance.
+     */
+    private applyStealthScripts;
     private checkAbort;
+    /**
+     * Scroll element vào viewport mượt mà — segments + delay.
+     * Chỉ scroll nếu element nằm ngoài viewport.
+     */
+    private smoothScrollToElement;
+    /**
+     * Pause execution for the given duration.
+     *
+     * @param ms - Duration in milliseconds
+     * @example await utils.sleep(2000); // wait 2 seconds
+     */
     sleep(ms: number): Promise<void>;
+    /**
+     * Wait for an element to appear and become visible in the DOM.
+     * Returns null if not found (soft fail — does NOT throw).
+     * Supports CSS selectors and XPath (auto-detected by `//` or `(` prefix).
+     *
+     * @param selector - CSS selector or XPath expression
+     * @param timeout - Max wait time in ms (default: 8000)
+     * @param scope - Optional Frame to search within
+     * @returns The element handle, or null if not found
+     *
+     * @example
+     * const el = await utils.waitForElement("#my-btn");
+     * if (el) await el.click();
+     */
     waitForElement(selector: string, timeout?: number, scope?: Frame): Promise<ElementHandle | null>;
-    click(target: string | ElementHandle, options?: {
+    /**
+     * Resolve an element: if waitTimeout > 0, wait for it; otherwise query directly with $().
+     */
+    private resolveElement;
+    /**
+     * Click on an element or at specific coordinates.
+     * Scrolls the element into view before clicking.
+     * Throws if the element is not found.
+     *
+     * @param target - CSS selector, XPath, ElementHandle, or `{ x, y }` coordinates
+     * @param options.delay - Delay in ms before clicking (default: 1000)
+     * @param options.waitTimeout - Max wait time for element to appear (default: 2000)
+     * @param options.frame - Optional Frame to search within
+     * @returns true on success
+     *
+     * @example
+     * await utils.click("#submit-btn");
+     * await utils.click("#btn", { delay: 0 });             // click immediately
+     * await utils.click({ x: 500, y: 300 });               // click at coordinates
+     * const pos = await utils.getPosition("#btn", { randomXY: true });
+     * await utils.click(pos!);                              // click random point inside element
+     */
+    click(target: string | ElementHandle | {
+        x: number;
+        y: number;
+    }, options?: {
         delay?: number;
-        timeout?: number;
+        waitTimeout?: number;
         frame?: Frame;
     }): Promise<boolean>;
+    /**
+     * Get the position (x, y) of an element.
+     * Returns center point by default, or a random point within bounds with `randomXY`.
+     *
+     * @param selector - CSS selector or XPath
+     * @param options.randomXY - If true, returns random point within element (10% margin from edges)
+     * @param options.waitTimeout - Max wait time for element (default: 2000ms)
+     * @param options.frame - Optional Frame to search within
+     * @returns `{ x, y }` or null if element not found / no bounding box
+     *
+     * @example
+     * const center = await utils.getPosition("#btn");
+     * const rand = await utils.getPosition("#btn", { randomXY: true });
+     * if (rand) await utils.click(rand);
+     */
+    getPosition(selector: string, options?: {
+        randomXY?: boolean;
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<{
+        x: number;
+        y: number;
+    } | null>;
+    /**
+     * Select a value from a `<select>` dropdown.
+     * Human-like flow: cursor moves to select → click to open → page.select() → close.
+     *
+     * NOTE: Native `<option>` elements CAN NOT be clicked via Puppeteer
+     * ("Node is either not clickable or not an Element").
+     * `page.select()` is the ONLY reliable method.
+     *
+     * @param selector - CSS selector or XPath of the `<select>` element
+     * @param value - The `value` attribute of the option to select
+     * @param options.delay - Delay before clicking (default: 500ms)
+     * @param options.waitTimeout - Max wait for element (default: 2000ms)
+     *
+     * @example
+     * await utils.select("#country", "vn");
+     */
+    select(selector: string, value: string, options?: {
+        delay?: number;
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<boolean>;
+    /**
+     * Type text into an input element. Throws if the element is not found.
+     *
+     * @param selector - CSS selector or XPath of the input
+     * @param text - The text to type
+     * @param options.mode - Typing mode:
+     *   - `"replace"` (default): Clear existing text, then type new text
+     *   - `"append"`: Type without clearing — appends to existing text
+     *   - `"paste"`: Set value directly via JS (fast, no keystroke simulation)
+     * @param options.delay - Delay between keystrokes in ms (default: 50). Ignored in paste mode.
+     * @param options.waitTimeout - Max wait time for element to appear in ms (default: 0 — instant)
+     * @param options.frame - Optional Frame to search within
+     * @returns true on success
+     *
+     * @example
+     * await utils.type("#email", "user@example.com");                    // replace mode
+     * await utils.type("#input", " more text", { mode: "append" });      // append
+     * await utils.type("#address", "0x1234...abcd", { mode: "paste" });  // instant paste
+     */
     type(selector: string, text: string, options?: {
+        /** Typing mode: replace (default) = clear then type, append = type without clearing, paste = set value directly */
+        mode?: "replace" | "append" | "paste";
         delay?: number;
+        waitTimeout?: number;
         frame?: Frame;
     }): Promise<boolean>;
-    getText(selector: string, frame?: Frame): Promise<string | null>;
+    /**
+     * Get the text content of an element. Returns null if not found (soft fail).
+     *
+     * @param selector - CSS selector or XPath
+     * @param options.waitTimeout - Max wait time for element to appear in ms (default: 0 — instant)
+     * @param options.frame - Optional Frame to search within
+     * @returns Trimmed text content, or null if element not found
+     *
+     * @example
+     * const price = await utils.getText(".price");
+     * const el = await utils.getText(".lazy-el", { waitTimeout: 8000 });
+     */
+    getText(selector: string, options?: {
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<string | null>;
+    /**
+     * Check if an element exists and is visible on the page.
+     * Returns false if not found (soft fail — does NOT throw).
+     *
+     * @param selector - CSS selector or XPath
+     * @param timeout - Max wait time in ms (default: 4000)
+     * @param frame - Optional Frame to search within
+     * @returns true if element exists and is visible
+     *
+     * @example
+     * if (await utils.exists("#popup-overlay")) {
+     *   await utils.click("#close-popup");
+     * }
+     */
     exists(selector: string, timeout?: number, frame?: Frame): Promise<boolean>;
+    /**
+     * Navigate the active page to a URL. Waits until the page fully loads.
+     * Throws on navigation failure or timeout.
+     *
+     * @param url - The URL to navigate to
+     * @param options.waitUntil - When to consider navigation complete (default: "load")
+     * @returns true on success
+     *
+     * @example
+     * await utils.goto("https://example.com");
+     * await utils.goto("https://app.com", { waitUntil: "networkidle0" });
+     */
     goto(url: string, options?: {
         waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
     }): Promise<boolean>;
+    /**
+     * Scroll the page or a container by a specific amount.
+     * Uses CDP mouseWheel events (human-like, not JS scrollBy).
+     *
+     * @param direction - "up" or "down"
+     * @param amount - Pixels to scroll
+     * @param options.container - CSS selector of scroll container
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     *
+     * @example
+     * await utils.scroll("down", 500);
+     * await utils.scroll("up", 200, { container: "#chat-messages" });
+     */
+    scroll(direction: "up" | "down", amount: number, options?: {
+        container?: string;
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * Scroll to the top or bottom of the page.
+     * Scrolls in segments with pauses — giống người lướt dần đến đích.
+     *
+     * @param position - "top" or "bottom"
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     *
+     * @example
+     * await utils.scrollTo("bottom");
+     * await utils.scrollTo("top");
+     */
+    scrollTo(position: "top" | "bottom", options?: {
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * Scroll an element into the viewport.
+     * Scrolls in segments with pauses — không nhảy tới đích.
+     *
+     * @param selector - CSS selector or XPath of the element
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     * @returns true if element found and scrolled
+     *
+     * @example
+     * await utils.scrollToElement("#footer");
+     * await utils.scrollToElement("//button[text()='Load more']");
+     */
+    scrollToElement(selector: string, options?: {
+        speed?: number;
+    }): Promise<boolean>;
+    /**
+     * Simulate natural browsing scroll — cuộn xuống xen kẽ lướt ngược, delay random.
+     * Giống người đang đọc/lướt web tự nhiên.
+     *
+     * @param options.duration - Thời gian scroll tính bằng giây (default: 5)
+     * @param options.direction - Main direction (default: "down")
+     * @param options.backChance - Chance to scroll back 0-1 (default: 0.15)
+     * @param options.backAmount - [min, max] px to scroll back (default: [50, 150])
+     * @param options.stepSize - [min, max] px per step (default: [200, 400])
+     * @param options.stepDelay - [min, max] ms delay between steps (default: [300, 800])
+     * @param options.container - CSS selector of scroll container
+     *
+     * @example
+     * await utils.randomScroll();                     // 5s lướt xuống
+     * await utils.randomScroll({ duration: 10 });     // 10s
+     * await utils.randomScroll({ backChance: 0.3, container: "#feed" });
+     */
+    randomScroll(options?: {
+        duration?: number;
+        direction?: "down" | "up";
+        backChance?: number;
+        backAmount?: [number, number];
+        stepSize?: [number, number];
+        stepDelay?: [number, number];
+        container?: string;
+    }): Promise<void>;
+    /**
+     * Wait for the current page to complete a navigation (e.g. after a form submit).
+     * Throws on timeout.
+     *
+     * @param options.timeout - Max wait time in ms (default: 60000)
+     * @param options.waitUntil - When to consider navigation complete (default: "load")
+     * @returns true on success
+     *
+     * @example
+     * await utils.click("#submit");
+     * await utils.waitForNavigation();
+     */
     waitForNavigation(options?: {
         timeout?: number;
         waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
     }): Promise<boolean>;
+    /**
+     * Take a screenshot of the active page. Returns null on failure (soft fail).
+     *
+     * @param path - Optional file path to save the screenshot. If omitted, returns base64 string.
+     * @returns Screenshot buffer (if path given) or base64 string, or null on failure
+     *
+     * @example
+     * await utils.screenshot("./debug.png");        // save to file
+     * const base64 = await utils.screenshot();       // get base64
+     */
     screenshot(path?: string): Promise<unknown>;
-    switchToPopup(matcher: string | RegExp, timeout?: number): Promise<puppeteer.Page | null>;
-    switchToTabIndex(index: number): Promise<puppeteer.Page | null>;
+    /**
+     * Switch scope into an iframe within the current page.
+     * After switching, all methods (click, type, exists...) operate inside the iframe.
+     * Use `activeMainFrame()` to exit back to the main page.
+     * Throws if the iframe is not found.
+     *
+     * @param selector - CSS selector or XPath of the iframe element
+     * @param options.waitTimeout - Max wait time for iframe element to appear in ms (default: 0 — instant)
+     * @returns The Frame handle
+     *
+     * @example
+     * await utils.activeIframe("#my-iframe");
+     * await utils.click("#btn-inside-iframe");
+     * await utils.activeMainFrame();
+     */
+    activeIframe(selector: string, options?: {
+        waitTimeout?: number;
+    }): Promise<Frame | null>;
+    /**
+     * Exit the current iframe and return to the main frame of the active page.
+     * After calling this, all methods operate on the main page (outside any iframe).
+     *
+     * @example
+     * await utils.activeIframe("#my-iframe");
+     * await utils.click("#btn-in-iframe");
+     * await utils.activeMainFrame();  // back to main page
+     */
+    activeMainFrame(): Promise<void>;
+    private _findNewTab;
+    private _findPopup;
+    /**
+     * Wait for a new tab to appear, but do NOT switch to it.
+     * The active page remains unchanged. Throws if no new tab appears before timeout.
+     *
+     * @param opts.matcher - String or RegExp to match the new tab's title or URL. If omitted, any new tab matches.
+     * @param opts.timeout - Max wait time in ms (default: 8000)
+     * @returns The new Page handle (without switching)
+     *
+     * @example
+     * await utils.click("#open-link");
+     * const page = await utils.waitForNewTab();
+     * const page = await utils.waitForNewTab({ timeout: 20000 });
+     * const page = await utils.waitForNewTab({ matcher: "Google" });
+     */
+    waitForNewTab(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * Switch to a new tab immediately (or wait if timeout is specified).
+     * After calling this, all methods operate on the new tab.
+     * Use `activeDefault()` to return to the original tab.
+     *
+     * @param opts.matcher - String or RegExp to match the new tab's title or URL
+     * @param opts.timeout - Max wait time in ms (default: 0 — instant, throws if not found)
+     * @returns The new Page handle (now active)
+     *
+     * @example
+     * await utils.click("#open-link");
+     * await utils.activeNewTab();                          // switch immediately
+     * await utils.activeNewTab({ timeout: 8000 });         // wait up to 8s
+     * await utils.type("#input", "hello");                  // types on the new tab
+     * await utils.activeDefault();                          // back to original tab
+     */
+    activeNewTab(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * Wait for a popup/tab matching the given criteria to appear, but do NOT switch to it.
+     * Throws if no matching popup appears before timeout.
+     *
+     * @param opts.matcher - String or RegExp to match title or URL. If omitted, any new popup matches.
+     * @param opts.timeout - Max wait time in ms (default: 8000)
+     * @returns The popup Page handle (without switching)
+     *
+     * @example
+     * await utils.click("#connect-wallet");
+     * const popup = await utils.waitForPopup({ matcher: "MetaMask" });
+     */
+    waitForPopup(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * Switch to a popup/tab immediately (or wait if timeout is specified).
+     * After calling this, all methods operate on the popup.
+     * Use `activeDefault()` to return to the original tab.
+     *
+     * @param opts.matcher - String or RegExp to match title or URL
+     * @param opts.timeout - Max wait time in ms (default: 0 — instant, throws if not found)
+     * @returns The popup Page handle (now active)
+     *
+     * @example
+     * await utils.click("#connect-wallet");
+     * await utils.activePopup({ matcher: "MetaMask" });
+     * await utils.click("#approve");         // clicks on the popup
+     * await utils.activeDefault();            // back to original tab
+     */
+    activePopup(opts?: {
+        matcher?: string | RegExp;
+        timeout?: number;
+    }): Promise<puppeteer_core.Page | null>;
+    /**
+     * Switch focus to a tab by its index (0-based, ordered by creation time).
+     * All subsequent methods (click, type, goto...) will operate on this tab.
+     * User interactions (opening tabs, clicking browser) do NOT affect the active tab.
+     * Throws if the index is out of range.
+     *
+     * @param index - Zero-based tab index
+     * @returns The Page handle of the activated tab
+     *
+     * @example
+     * await utils.activeTab(1);        // switch to second tab
+     * await utils.click("#btn");       // clicks on tab 1
+     * await utils.activeTab(0);        // back to first tab
+     */
+    activeTab(index: number): Promise<puppeteer_core.Page | null>;
+    /**
+     * Close the currently active tab and switch back to the default page.
+     *
+     * @example
+     * await utils.activeTab(1);
+     * await utils.closeCurrentTab();  // closes tab 1, returns to tab 0
+     */
     closeCurrentTab(): Promise<void>;
+    /**
+     * Close all tabs except the currently active one.
+     *
+     * @example
+     * await utils.closeOtherTabs();  // keeps only the active tab open
+     */
     closeOtherTabs(): Promise<void>;
     /**
-     * Close ALL tabs (including the current one).
-     * Useful for full cleanup before flow ends.
+     * Close ALL tabs including the current one.
+     * Useful for full cleanup before a flow ends.
+     *
+     * @example
+     * await utils.closeAllTabs();
      */
     closeAllTabs(): Promise<void>;
     /**
-     * Switch back to the default (initial) page — the page stored in context.
-     * Typically used after switchToPopup() to return to the main tab.
+     * Switch back to the default (initial) tab — the first tab opened when the flow started.
+     * Resets both the active page and active frame (exits any iframe).
+     * Typically used after `activePopup()` or `activeTab()` to return to the main tab.
+     *
+     * @returns The default Page handle
+     *
+     * @example
+     * await utils.activePopup({ matcher: "MetaMask" });
+     * await utils.click("#approve");
+     * await utils.activeDefault();  // back to original tab
+     */
+    activeDefault(): Promise<puppeteer_core.Page>;
+    /**
+     * Log a config object in a readable format.
+     *
+     * @param config - Key-value object to log
+     * @param label - Label for the log entry (default: "Config")
      */
-    switchToDefault(): Promise<puppeteer.Page>;
     logConfig(config: Record<string, unknown>, label?: string): Promise<void>;
+    /** Log the current profile input values for debugging. */
     logProfileInput(): Promise<void>;
     /**
-     * Log toàn bộ output hiện tại (bao gồm cả giá trị từ lần chạy trước và giá trị mới ghi).
-     * Dùng để debug — xem giá trị output hiện tại.
+     * Log all current output values (including values from previous runs and newly written values).
+     * Useful for debugging — see what outputs have been set.
      */
     logProfileOutput(): Promise<void>;
+    /** Log the current global input values for debugging. */
     logGlobalInput(): Promise<void>;
     /**
-     * Ghi kết quả tự do cho profile đang chạy.
-     * Gửi qua kênh riêng (type: "profile_output") — không lẫn log.
-     * Đồng thời log ra console/UI để flow dev dễ debug.
+     * Write an output value for the current profile.
+     * Dispatched via a dedicated channel (type: "profile_output") — separate from logs.
+     * Also logs the value to console/UI for debugging.
+     *
+     * ⚠️ Key must be defined in `config.output[]` — throws Error if invalid.
      *
-     * ⚠️ Key phải được định nghĩa trong config.output[] — nếu không sẽ throw Error.
+     * Accepted value types:
+     * - `string | number | boolean`
+     * - `Array` (max 20 elements, each must be primitive)
+     * - `Object` (max 10 entries, values must be primitive)
      *
-     * value hợp lệ:
-     * - string | number | boolean
-     * - array tối đa 20 phần tử (primitive)
-     * - object 1 cấp tối đa 10 entry (value phải là primitive)
+     * @param key - Output key (must match config.output definition)
+     * @param value - The value to write
+     *
+     * @example
+     * await utils.writeOutput("status", "success");
+     * await utils.writeOutput("balance", 1234.56);
+     * await utils.writeOutput("tokens", ["ETH", "USDT"]);
      */
     writeOutput(key: InferOutputKeys<TConfig>, value: ProfileOutputValue): Promise<void>;
     /**
-     * Cập nhật lại một field trong profileInput của profile đang chạy.
-     * key phải là field đã được định nghĩa trong profileInput schema.
-     * Kết quả được gửi về server để update AgentFlowConfig sau khi execution xong.
+     * Update a profile input field for the currently running profile.
+     * The key must be defined in the profileInput schema.
+     * The updated value is sent to the server to persist in AgentFlowConfig after execution.
+     *
+     * @param key - Profile input key (must match schema definition)
+     * @param value - The new value (string, number, or boolean)
+     *
+     * @example
+     * await utils.writeProfileInput("lastLoginDate", "2024-01-15");
+     * await utils.writeProfileInput("retryCount", 3);
      */
     writeProfileInput(key: InferProfileInputKeys<TConfig>, value: string | number | boolean): Promise<void>;
     private sanitizeOutputValue;