@roll-agent/browser-use-agent 0.26.1 → 0.27.0

package/dist/goal/form-handoff.d.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+/** A summary is not a fresh locator or an independent certification of completion. */
+export declare const FormHandoffSchema: z.ZodObject<{
+    observationFresh: z.ZodBoolean;
+    diagnosticsOmitted: z.ZodLiteral<true>;
+    totalSteps: z.ZodNumber;
+    omittedSteps: z.ZodNumber;
+    fields: z.ZodArray<z.ZodObject<Pick<{
+        id: z.ZodString;
+        name: z.ZodString;
+        intent: z.ZodEnum<["set", "preserve"]>;
+        comparison: z.ZodEnum<["auto", "literal", "semantic"]>;
+        expected: z.ZodOptional<z.ZodString>;
+        binding: z.ZodOptional<z.ZodObject<{
+            identity: z.ZodString;
+            readOnlyDisplay: z.ZodOptional<z.ZodLiteral<true>>;
+            key: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            role: z.ZodString;
+            fieldLabel: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            role: string;
+            name: string;
+            identity: string;
+            key?: string | undefined;
+            fieldLabel?: string | undefined;
+            readOnlyDisplay?: true | undefined;
+        }, {
+            role: string;
+            name: string;
+            identity: string;
+            key?: string | undefined;
+            fieldLabel?: string | undefined;
+            readOnlyDisplay?: true | undefined;
+        }>>;
+        entry: z.ZodOptional<z.ZodObject<{
+            identity: z.ZodString;
+            readOnlyDisplay: z.ZodOptional<z.ZodLiteral<true>>;
+            key: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            role: z.ZodString;
+            fieldLabel: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            role: string;
+            name: string;
+            identity: string;
+            key?: string | undefined;
+            fieldLabel?: string | undefined;
+            readOnlyDisplay?: true | undefined;
+        }, {
+            role: string;
+            name: string;
+            identity: string;
+            key?: string | undefined;
+            fieldLabel?: string | undefined;
+            readOnlyDisplay?: true | undefined;
+        }>>;
+        entryProof: z.ZodOptional<z.ZodObject<{
+            fingerprint: z.ZodString;
+            status: z.ZodEnum<["satisfied", "unsatisfied", "unknown"]>;
+        }, "strip", z.ZodTypeAny, {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            fingerprint: string;
+        }, {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            fingerprint: string;
+        }>>;
+        initial: z.ZodOptional<z.ZodString>;
+        current: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["unknown", "unsatisfied", "satisfied"]>;
+        reason: z.ZodString;
+        fingerprint: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            optionsKey: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            label: string;
+            key: string;
+            optionsKey: string;
+        }, {
+            label: string;
+            key: string;
+            optionsKey: string;
+        }>>;
+        semanticProof: z.ZodOptional<z.ZodObject<{
+            fingerprint: z.ZodString;
+            status: z.ZodEnum<["satisfied", "unsatisfied"]>;
+        }, "strip", z.ZodTypeAny, {
+            status: "satisfied" | "unsatisfied";
+            fingerprint: string;
+        }, {
+            status: "satisfied" | "unsatisfied";
+            fingerprint: string;
+        }>>;
+    }, "status" | "id" | "name" | "reason" | "intent"> & {
+        expected: z.ZodOptional<z.ZodString>;
+        current: z.ZodOptional<z.ZodString>;
+        valueTruncated: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        status: "unknown" | "satisfied" | "unsatisfied";
+        id: string;
+        name: string;
+        reason: string;
+        intent: "set" | "preserve";
+        valueTruncated: boolean;
+        expected?: string | undefined;
+        current?: string | undefined;
+    }, {
+        status: "unknown" | "satisfied" | "unsatisfied";
+        id: string;
+        name: string;
+        reason: string;
+        intent: "set" | "preserve";
+        valueTruncated: boolean;
+        expected?: string | undefined;
+        current?: string | undefined;
+    }>, "many">;
+    next: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    fields: {
+        status: "unknown" | "satisfied" | "unsatisfied";
+        id: string;
+        name: string;
+        reason: string;
+        intent: "set" | "preserve";
+        valueTruncated: boolean;
+        expected?: string | undefined;
+        current?: string | undefined;
+    }[];
+    observationFresh: boolean;
+    diagnosticsOmitted: true;
+    totalSteps: number;
+    omittedSteps: number;
+    next: string;
+}, {
+    fields: {
+        status: "unknown" | "satisfied" | "unsatisfied";
+        id: string;
+        name: string;
+        reason: string;
+        intent: "set" | "preserve";
+        valueTruncated: boolean;
+        expected?: string | undefined;
+        current?: string | undefined;
+    }[];
+    observationFresh: boolean;
+    diagnosticsOmitted: true;
+    totalSteps: number;
+    omittedSteps: number;
+    next: string;
+}>;

package/dist/goal/form-loop-progress.d.ts

@@ -0,0 +1,9 @@
+import type { GoalSnapshot } from "./observation.ts";
+import type { BrowserOperateOutput } from "./contracts.ts";
+import type { FormState } from "./form-context.ts";
+export declare function createFormLoopProgress(): {
+    documentId: string;
+    visits: Map<string, number>;
+};
+/** Detect revisiting the same form/option state, not merely a long sequence of actions. */
+export declare function observeFormLoopProgress(memory: ReturnType<typeof createFormLoopProgress>, snapshot: GoalSnapshot, form: FormState, previousAction?: Pick<BrowserOperateOutput["steps"][number], "operation" | "executed" | "error">): boolean;

package/dist/goal/form-policy.d.ts

@@ -0,0 +1,13 @@
+import type { DecisionRequest } from "./decisions.ts";
+import type { GoalSnapshot } from "./observation.ts";
+import type { PickerState } from "./picker-state.ts";
+import type { ExecutionContext } from "./execution-context.ts";
+import type { FormControl } from "./form-context.ts";
+export declare function formReady(context: ExecutionContext, snapshot: GoalSnapshot, pickers: PickerState): boolean;
+export declare function formActionOwner(context: ExecutionContext, ref: string, controls: readonly FormControl[], pickers: PickerState): string | undefined;
+export declare function withFormContext(request: DecisionRequest, context: ExecutionContext | undefined, snapshot: GoalSnapshot, controls: readonly FormControl[], pickers: PickerState, entryCandidates: readonly FormControl[]): DecisionRequest;
+/** Commit only current-observation bindings/judgments; a change invalidates the old action branch. */
+export declare function acceptFormDecisions(context: ExecutionContext, snapshot: GoalSnapshot, controls: readonly FormControl[], choices: Record<string, string>): {
+    changed: boolean;
+    error?: string;
+};

package/dist/goal/host.d.ts

@@ -0,0 +1,6 @@
+import type { AgentContext } from "@roll-agent/sdk";
+import type { NativeCdpFrameTree } from "@roll-agent/browser";
+import type { BrowserOperateInput, BrowserOperateOutput } from "./contracts.ts";
+export declare function permittedFrames(tree: NativeCdpFrameTree, origins: readonly string[]): Set<string>;
+export declare function resolveOperateEngine(requested: BrowserOperateInput["engine"], env: NodeJS.ProcessEnv): NonNullable<BrowserOperateInput["engine"]>;
+export declare function operateBrowser(rawInput: BrowserOperateInput, ctx: AgentContext): Promise<BrowserOperateOutput>;

package/dist/goal/interaction-feedback.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import type { GoalSnapshot } from "./observation.ts";
+import type { ExecutionContext } from "./execution-context.ts";
+import type { DecisionRequest } from "./decisions.ts";
+declare const AttemptSchema: z.ZodObject<{
+    identity: z.ZodString;
+    operation: z.ZodEnum<["CLICK", "TYPE_TEXT", "SELECT"]>;
+    target: z.ZodString;
+    epoch: z.ZodString;
+    attempts: z.ZodNumber;
+    feedback: z.ZodArray<z.ZodString, "many">;
+    judged: z.ZodBoolean;
+    prerequisite: z.ZodOptional<z.ZodObject<{
+        fieldId: z.ZodString;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        fieldId: string;
+        signature: string;
+    }, {
+        fieldId: string;
+        signature: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    target: string;
+    epoch: string;
+    attempts: number;
+    identity: string;
+    operation: "CLICK" | "TYPE_TEXT" | "SELECT";
+    feedback: string[];
+    judged: boolean;
+    prerequisite?: {
+        fieldId: string;
+        signature: string;
+    } | undefined;
+}, {
+    target: string;
+    epoch: string;
+    attempts: number;
+    identity: string;
+    operation: "CLICK" | "TYPE_TEXT" | "SELECT";
+    feedback: string[];
+    judged: boolean;
+    prerequisite?: {
+        fieldId: string;
+        signature: string;
+    } | undefined;
+}>;
+type Attempt = z.infer<typeof AttemptSchema>;
+export declare function createInteractionFeedback(): {
+    documentId: string;
+    attempts: Map<string, {
+        target: string;
+        epoch: string;
+        attempts: number;
+        identity: string;
+        operation: "CLICK" | "TYPE_TEXT" | "SELECT";
+        feedback: string[];
+        judged: boolean;
+        prerequisite?: {
+            fieldId: string;
+            signature: string;
+        } | undefined;
+    }>;
+    pending: {
+        attempt: Attempt;
+        beforeText: string[];
+        beforeEffect: string;
+    } | undefined;
+    questionKey: string | undefined;
+};
+export type InteractionFeedback = ReturnType<typeof createInteractionFeedback>;
+export declare function observeInteractionFeedback(memory: InteractionFeedback, snapshot: GoalSnapshot, context: ExecutionContext): void;
+export declare function recordInteractionAttempt(memory: InteractionFeedback, snapshot: GoalSnapshot, action: {
+    operation: string;
+    identity: string;
+    target: string;
+    executed: boolean;
+    error?: string;
+}): void;
+export declare function withInteractionFeedback(request: DecisionRequest, memory: InteractionFeedback, snapshot: GoalSnapshot, context: ExecutionContext): DecisionRequest;
+export declare function acceptInteractionFeedback(memory: InteractionFeedback, context: ExecutionContext, choices: Record<string, string>): boolean;
+export {};

package/dist/goal/loop.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserElementRef } from "@roll-agent/browser";
+import type { GoalSnapshot } from "./observation.ts";
+import type { BrowserOperateInput, BrowserOperateOutput } from "./contracts.ts";
+import type { DecisionProvider, DecisionRequest } from "./decisions.ts";
+export type GoalDriver = {
+    observe: (dependencyIdentities?: readonly string[]) => Promise<GoalSnapshot>;
+    invoke: (method: string, params: unknown[]) => Promise<unknown>;
+    actionExecuted: () => boolean;
+    checkTarget?: (snapshot: GoalSnapshot, ref: BrowserElementRef) => Promise<boolean>;
+};
+export declare function buildDecisionRequest(input: BrowserOperateInput, snapshot: GoalSnapshot, history: BrowserOperateOutput["steps"], requirementIndex?: number, suppressedClicks?: ReadonlySet<string>, pendingDialogs?: readonly string[]): DecisionRequest;
+export declare function runBrowserGoal(input: BrowserOperateInput, driver: GoalDriver, decide: DecisionProvider, signal: AbortSignal): Promise<BrowserOperateOutput>;

package/dist/goal/observation-retry.d.ts

@@ -0,0 +1,3 @@
+import type { GoalDriver } from "./loop.ts";
+/** Retry only a complete readonly observation, never a browser action. */
+export declare function createRetryingGoalObserver(read: GoalDriver["observe"], signal: AbortSignal, discardPartial?: () => void): GoalDriver["observe"];