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

package/dist/goal/decisions.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import type { AgentContext } from "@roll-agent/sdk";
+export declare const ChoiceQuestionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    instructions: z.ZodString;
+    criteria: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+}, {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+}>;
+export type ChoiceQuestion = z.infer<typeof ChoiceQuestionSchema>;
+export type DecisionRequest = {
+    state: unknown;
+    /** Host-only observation refs needed by adapters, retained through preview compaction. */
+    observationRefs?: string[];
+    questions: Record<string, ChoiceQuestion>;
+    /** Host-only dispatch metadata; not part of the provider HTTP body. */
+    routing?: {
+        head: string;
+        targets: Record<string, string>;
+    };
+    /** Additional independent heads and the conditional evidence answers actually consumed. */
+    evidenceRouting?: Record<string, Record<string, string[]>>;
+};
+export type DecisionResult = {
+    choices: Record<string, string>;
+    requestedModel: string;
+    resolvedModel: string;
+    provider: string;
+    elapsedMs: number;
+    attempts?: number;
+    distributions?: Record<string, {
+        probabilities: Record<string, number>;
+        confidence?: number;
+    }>;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cost?: number;
+    };
+};
+export type DecisionProvider = (request: DecisionRequest, signal: AbortSignal) => Promise<DecisionResult>;
+export declare function validateChoices(request: DecisionRequest, choices: Record<string, string>): void;
+export declare function createJevProvider(options: {
+    apiKey: string;
+    model: string;
+    fetch?: typeof fetch;
+    pause?: (ms: number, signal: AbortSignal) => Promise<void>;
+}): DecisionProvider;
+export declare function createSamplingProvider(ctx: AgentContext): DecisionProvider;

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

@@ -0,0 +1,7 @@
+import type { NativeCdpController } from "@roll-agent/browser";
+import { inspectGoalControls } from "./observation.ts";
+import type { GoalSnapshot } from "./observation.ts";
+/** Retain handles only for read-only dependency inspection, never AX resurrection.
+ * A replaced/disconnected node, document change or missing modal fails closed.
+ */
+export declare function createDependencyObserver(controller: Parameters<typeof inspectGoalControls>[0] & Pick<NativeCdpController, "getFrameTree">, origins: readonly string[], signal: AbortSignal): (snapshot: GoalSnapshot, identities?: readonly string[]) => Promise<GoalSnapshot>;

package/dist/goal/execution-context.d.ts

@@ -0,0 +1,593 @@
+import { z } from "zod";
+import type { ReadTask, TaskProgress } from "./task-progress.ts";
+import type { FormControl, FormState, FormTask } from "./form-context.ts";
+import type { GoalSnapshot } from "./observation.ts";
+export declare const ExecutionSummarySchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    revision: z.ZodNumber;
+    documentChanged: z.ZodBoolean;
+    latestObservation: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodString>;
+    changes: z.ZodArray<z.ZodObject<{
+        observationId: z.ZodString;
+        identity: z.ZodString;
+        field: z.ZodString;
+        kind: z.ZodEnum<["changed", "became_unknown", "appeared"]>;
+        before: z.ZodOptional<z.ZodString>;
+        after: z.ZodOptional<z.ZodString>;
+        afterAction: z.ZodOptional<z.ZodString>;
+        scope: z.ZodEnum<["delegated", "preserved", "unassigned"]>;
+    }, "strip", z.ZodTypeAny, {
+        scope: "delegated" | "preserved" | "unassigned";
+        kind: "changed" | "became_unknown" | "appeared";
+        field: string;
+        observationId: string;
+        identity: string;
+        before?: string | undefined;
+        after?: string | undefined;
+        afterAction?: string | undefined;
+    }, {
+        scope: "delegated" | "preserved" | "unassigned";
+        kind: "changed" | "became_unknown" | "appeared";
+        field: string;
+        observationId: string;
+        identity: string;
+        before?: string | undefined;
+        after?: string | undefined;
+        afterAction?: string | undefined;
+    }>, "many">;
+    lastAction: z.ZodOptional<z.ZodObject<{
+        operation: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+        executed: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        executed: boolean;
+        operation: string;
+        target?: string | undefined;
+        error?: string | undefined;
+    }, {
+        executed: boolean;
+        operation: string;
+        target?: string | undefined;
+        error?: string | undefined;
+    }>>;
+    form: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<["create", "edit"]>;
+        stopAt: z.ZodEnum<["applied", "current-view"]>;
+        fields: z.ZodArray<z.ZodObject<{
+            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;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }, {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }>, "many">;
+        focus: z.ZodOptional<z.ZodString>;
+        panel: z.ZodOptional<z.ZodObject<{
+            key: z.ZodString;
+            status: z.ZodEnum<["pending", "accepted", "rejected"]>;
+            queryIdentity: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        }, {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "create" | "edit";
+        stopAt: "applied" | "current-view";
+        fields: {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }[];
+        panel?: {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        } | undefined;
+        focus?: string | undefined;
+    }, {
+        mode: "create" | "edit";
+        stopAt: "applied" | "current-view";
+        fields: {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }[];
+        panel?: {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        } | undefined;
+        focus?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    changes: {
+        scope: "delegated" | "preserved" | "unassigned";
+        kind: "changed" | "became_unknown" | "appeared";
+        field: string;
+        observationId: string;
+        identity: string;
+        before?: string | undefined;
+        after?: string | undefined;
+        afterAction?: string | undefined;
+    }[];
+    revision: number;
+    invocationId: string;
+    documentChanged: boolean;
+    form?: {
+        mode: "create" | "edit";
+        stopAt: "applied" | "current-view";
+        fields: {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }[];
+        panel?: {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        } | undefined;
+        focus?: string | undefined;
+    } | undefined;
+    focus?: string | undefined;
+    latestObservation?: string | undefined;
+    lastAction?: {
+        executed: boolean;
+        operation: string;
+        target?: string | undefined;
+        error?: string | undefined;
+    } | undefined;
+}, {
+    changes: {
+        scope: "delegated" | "preserved" | "unassigned";
+        kind: "changed" | "became_unknown" | "appeared";
+        field: string;
+        observationId: string;
+        identity: string;
+        before?: string | undefined;
+        after?: string | undefined;
+        afterAction?: string | undefined;
+    }[];
+    revision: number;
+    invocationId: string;
+    documentChanged: boolean;
+    form?: {
+        mode: "create" | "edit";
+        stopAt: "applied" | "current-view";
+        fields: {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }[];
+        panel?: {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        } | undefined;
+        focus?: string | undefined;
+    } | undefined;
+    focus?: string | undefined;
+    latestObservation?: string | undefined;
+    lastAction?: {
+        executed: boolean;
+        operation: string;
+        target?: string | undefined;
+        error?: string | undefined;
+    } | undefined;
+}>;
+export type ExecutionContext = {
+    summary: z.infer<typeof ExecutionSummarySchema>;
+    initial: Map<string, string>;
+    previous: Map<string, {
+        name: string;
+        value: string;
+    }>;
+    unknown: Set<string>;
+    ownership: Map<string, {
+        field: string;
+        intent: "set" | "preserve";
+    }>;
+    documentId?: string;
+    read?: TaskProgress;
+    form?: FormState;
+};
+export declare function createExecutionContext(input: {
+    readTask?: ReadTask | undefined;
+    formTask?: FormTask | undefined;
+    values: readonly {
+        name: string;
+        text: string;
+    }[];
+}): ExecutionContext;
+export declare function observeExecution(context: ExecutionContext, snapshot: GoalSnapshot, controls: readonly FormControl[], readTask?: ReadTask): boolean;
+export declare function executionSummary(context: ExecutionContext): {
+    focus?: string | undefined;
+    form?: {
+        mode: "create" | "edit";
+        stopAt: "applied" | "current-view";
+        fields: {
+            status: "unknown" | "satisfied" | "unsatisfied";
+            id: string;
+            name: string;
+            reason: string;
+            intent: "set" | "preserve";
+            comparison: "auto" | "literal" | "semantic";
+            expected?: string | undefined;
+            target?: {
+                label: string;
+                key: string;
+                optionsKey: string;
+            } | undefined;
+            fingerprint?: string | undefined;
+            binding?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entry?: {
+                role: string;
+                name: string;
+                identity: string;
+                key?: string | undefined;
+                fieldLabel?: string | undefined;
+                readOnlyDisplay?: true | undefined;
+            } | undefined;
+            entryProof?: {
+                status: "unknown" | "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+            initial?: string | undefined;
+            current?: string | undefined;
+            semanticProof?: {
+                status: "satisfied" | "unsatisfied";
+                fingerprint: string;
+            } | undefined;
+        }[];
+        panel?: {
+            status: "pending" | "rejected" | "accepted";
+            key: string;
+            queryIdentity?: string | undefined;
+        } | undefined;
+        focus?: string | undefined;
+    } | undefined;
+    changes: {
+        scope: "delegated" | "preserved" | "unassigned";
+        kind: "changed" | "became_unknown" | "appeared";
+        field: string;
+        observationId: string;
+        identity: string;
+        before?: string | undefined;
+        after?: string | undefined;
+        afterAction?: string | undefined;
+    }[];
+    revision: number;
+    invocationId: string;
+    documentChanged: boolean;
+    latestObservation?: string | undefined;
+    lastAction?: {
+        executed: boolean;
+        operation: string;
+        target?: string | undefined;
+        error?: string | undefined;
+    } | undefined;
+};
+export declare function recordExecutionAction(context: ExecutionContext, action: {
+    operation: string;
+    target?: string;
+    executed: boolean;
+    error?: string;
+}, fieldId?: string): void;