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

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

@@ -0,0 +1,3 @@
+import type { BrowserOperateOutput } from "./contracts.ts";
+/** Tool-boundary form handoff. The internal loop result remains intact for direct consumers. */
+export declare function compactFormOperateOutput(output: BrowserOperateOutput): BrowserOperateOutput;

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

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export declare const PickerEvidenceSchema: z.ZodObject<{
+    part: z.ZodEnum<["trigger", "option"]>;
+    relationship: z.ZodEnum<["aria", "local-dom", "unknown"]>;
+    triggerPath: z.ZodOptional<z.ZodString>;
+    panelPaths: z.ZodArray<z.ZodString, "many">;
+    label: z.ZodOptional<z.ZodString>;
+    labelSource: z.ZodOptional<z.ZodEnum<["label", "placeholder", "empty-display"]>>;
+    expanded: z.ZodOptional<z.ZodBoolean>;
+    panelVisible: z.ZodOptional<z.ZodBoolean>;
+    selection: z.ZodEnum<["empty", "value", "unknown"]>;
+    selectionEvidence: z.ZodEnum<["native-select", "backing-input", "unknown"]>;
+    committedText: z.ZodOptional<z.ZodString>;
+    queryText: z.ZodOptional<z.ZodString>;
+    optionText: z.ZodOptional<z.ZodString>;
+    optionLabel: z.ZodOptional<z.ZodString>;
+    optionPath: z.ZodOptional<z.ZodString>;
+    optionSelected: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    selection: "value" | "unknown" | "empty";
+    part: "option" | "trigger";
+    relationship: "unknown" | "aria" | "local-dom";
+    panelPaths: string[];
+    selectionEvidence: "unknown" | "native-select" | "backing-input";
+    label?: string | undefined;
+    expanded?: boolean | undefined;
+    triggerPath?: string | undefined;
+    labelSource?: "label" | "placeholder" | "empty-display" | undefined;
+    panelVisible?: boolean | undefined;
+    committedText?: string | undefined;
+    queryText?: string | undefined;
+    optionText?: string | undefined;
+    optionLabel?: string | undefined;
+    optionPath?: string | undefined;
+    optionSelected?: boolean | undefined;
+}, {
+    selection: "value" | "unknown" | "empty";
+    part: "option" | "trigger";
+    relationship: "unknown" | "aria" | "local-dom";
+    panelPaths: string[];
+    selectionEvidence: "unknown" | "native-select" | "backing-input";
+    label?: string | undefined;
+    expanded?: boolean | undefined;
+    triggerPath?: string | undefined;
+    labelSource?: "label" | "placeholder" | "empty-display" | undefined;
+    panelVisible?: boolean | undefined;
+    committedText?: string | undefined;
+    queryText?: string | undefined;
+    optionText?: string | undefined;
+    optionLabel?: string | undefined;
+    optionPath?: string | undefined;
+    optionSelected?: boolean | undefined;
+}>;
+export type PickerEvidence = z.infer<typeof PickerEvidenceSchema>;
+/** Fixed read-only DOM code. No class names, site labels, coordinates or desired values. */
+export declare const INSPECT_PICKER = "function(pathFor) {\n  const el=this, doc=el.ownerDocument, view=doc.defaultView;\n  if(el.getRootNode()!==doc)return undefined;\n  const clean=s=>String(s||'').replace(/[\\uE000-\\uF8FF]/g,'').replace(/\\s+/g,' ').trim();\n  const panelSelector='ul,ol,[role=\"listbox\"],[role=\"menu\"],[role=\"tree\"],[role=\"grid\"],[role=\"dialog\"],dialog';\n  const optionSelector='li,option,[role=\"option\"],[role=\"menuitem\"],[role=\"treeitem\"]';\n  const triggerSelector='input,select,button,[tabindex],[role=\"combobox\"],[aria-haspopup],[aria-controls],[aria-owns]';\n  const ids=node=>[...(node.getAttribute('aria-controls')||'').split(/\\s+/),...(node.getAttribute('aria-owns')||'').split(/\\s+/)].filter(Boolean);\n  const explicitPanels=node=>ids(node).map(id=>doc.getElementById(id)).filter(p=>p && p!==node);\n  const hiddenValue=node=>{\n    const inputs=[...node.querySelectorAll('input[type=\"hidden\"]')];\n    return inputs.length===1?inputs[0]:undefined;\n  };\n  // A unique visible text input paired with one hidden selection token is a\n  // grounded autocomplete even when the application omits ARIA combobox markup.\n  const inputBacking=node=>{\n    if(node.tagName!=='INPUT' || !['text','search',''].includes(node.getAttribute('type')||''))return undefined;\n    for(let p=node.parentElement,depth=0;p && p!==doc.body && p.tagName!=='FORM' && depth<2;p=p.parentElement,depth++){\n      const fields=[...p.querySelectorAll('input:not([type=\"hidden\"]),textarea,select')];\n      if(fields.length>1)return undefined;\n      const hidden=[...p.querySelectorAll('input[type=\"hidden\"]')];\n      if(fields.length===1 && fields[0]===node && hidden.length===1)return hidden[0];\n    }\n    return undefined;\n  };\n  const triggerLike=node=>Boolean(inputBacking(node)) ||node.tagName==='SELECT' || node.getAttribute('role')==='combobox' ||\n    Boolean(node.getAttribute('aria-haspopup') && node.getAttribute('aria-haspopup')!=='false') ||\n    explicitPanels(node).some(p=>p.matches(panelSelector)||p.querySelector('[role=\"listbox\"],[role=\"menu\"],[role=\"tree\"]')) ||\n    (node.tabIndex>=0 && hiddenValue(node));\n  const triggersWithin=node=>{\n    const all=[...node.querySelectorAll(triggerSelector)].filter(triggerLike);\n    return all.filter(t=>!all.some(other=>other!==t && other.contains(t)));\n  };\n  const visible=node=>{\n    if(!node.isConnected || !node.getClientRects().length)return false;\n    for(let p=node;p;p=p.parentElement){const s=view.getComputedStyle(p);if(p.hidden || p.getAttribute('aria-hidden')==='true' || s.display==='none' || s.visibility!=='visible' || s.opacity==='0')return false;}\n    return true;\n  };\n  const localPanels=trigger=>{\n    if(trigger.tagName==='SELECT')return [];\n    const nested=[...trigger.querySelectorAll(panelSelector)].filter(p=>p.querySelector(optionSelector));\n    if(nested.length && !triggersWithin(trigger).length)return nested.filter(p=>!nested.some(other=>other!==p && other.contains(p)));\n    for(let parent=trigger.parentElement,depth=0;parent && parent!==doc.body && depth<5;parent=parent.parentElement,depth++){\n      const triggers=triggersWithin(parent);\n      if(triggers.length>1)return [];\n      if(triggers.length!==1 || triggers[0]!==trigger)continue;\n      const panels=[...parent.querySelectorAll(panelSelector)].filter(p=>!trigger.contains(p) && p.querySelector(optionSelector));\n      if(panels.length)return panels.filter(p=>!panels.some(other=>other!==p && other.contains(p)));\n    }\n    return [];\n  };\n  const option=el.closest(optionSelector);\n  const ownRole=option && option.getAttribute('role');\n  let trigger,panels=[],relationship='unknown',part;\n  if(triggerLike(el) && !option){\n    trigger=el;part='trigger';panels=explicitPanels(el);\n    if(panels.length)relationship='aria';else {panels=localPanels(el);if(panels.length)relationship='local-dom';}\n    if(el.tagName!=='SELECT' && !panels.length && !el.hasAttribute('aria-haspopup') && el.getAttribute('role')!=='combobox' && !inputBacking(el))return undefined;\n  }else if(option){\n    part='option';const panel=option.closest(panelSelector);\n    if(!panel && option.tagName!=='OPTION')return undefined;\n    const all=[...doc.querySelectorAll('[aria-controls],[aria-owns]')];\n    const explicit=all.length<=512 ? all.filter(t=>triggerLike(t) && explicitPanels(t).some(p=>p.contains(option))) : [];\n    let ambiguous=explicit.length>1 || all.length>512;\n    if(explicit.length===1){trigger=explicit[0];panels=explicitPanels(trigger);relationship='aria';}\n    if(!trigger && !ambiguous && panel){\n      for(let parent=panel.parentElement,depth=0;parent && parent!==doc.body && depth<5;parent=parent.parentElement,depth++){\n        const triggers=triggersWithin(parent).filter(t=>!panel.contains(t));\n        if(triggers.length>1){ambiguous=true;break;}\n        if(triggers.length===1){\n          const candidate=triggers[0],owned=explicitPanels(candidate).length?explicitPanels(candidate):localPanels(candidate);\n          if(owned.some(p=>p.contains(option))){trigger=candidate;panels=owned;relationship='local-dom';break;}\n        }\n      }\n    }\n    if(!trigger && !ambiguous && !['option','menuitem','treeitem'].includes(ownRole))return undefined;\n  }else return undefined;\n  const result={part,relationship,panelPaths:panels.map(pathFor).filter(Boolean),selection:'unknown',selectionEvidence:'unknown'};\n  if(option && part==='option'){\n    result.optionText=clean(option.innerText||option.textContent).slice(0,2000);\n    result.optionLabel=clean(option.getAttribute('aria-label') || (option.innerText||option.textContent||'').split(/\\n/).find(line=>line.trim()) || '').slice(0,2000);\n    const optionPath=pathFor(option);if(optionPath)result.optionPath=optionPath;\n    if(option.hasAttribute('aria-selected'))result.optionSelected=option.getAttribute('aria-selected')==='true';\n    else if(option.tagName==='OPTION')result.optionSelected=option.selected;\n  }\n  if(!trigger)return result;\n  const path=pathFor(trigger);if(path)result.triggerPath=path;else result.relationship='unknown';\n  const label=clean(trigger.getAttribute('aria-label') || [...(trigger.labels||[])].map(l=>l.textContent).join(' ') ||\n    (trigger.getAttribute('aria-labelledby')||'').split(/\\s+/).map(id=>doc.getElementById(id)?.textContent||'').join(' '));\n  if(label){result.label=label.slice(0,200);result.labelSource='label';}\n  const backing=inputBacking(trigger);\n  const hidden=hiddenValue(trigger)||backing,display=[];\n  const walker=doc.createTreeWalker(trigger,4);let node;\n  while((node=walker.nextNode())){\n    const parent=node.parentElement;\n    if(parent && visible(parent) && !parent.closest('script,style') && !panels.some(p=>p.contains(parent)))display.push(node.textContent||'');\n  }\n  const text=backing?clean(trigger.value):clean(display.join(''));\n  if(trigger.tagName==='SELECT'){\n    result.selection=trigger.selectedIndex<0 || (trigger.required && trigger.value==='')?'empty':'value';result.selectionEvidence='native-select';\n    if(result.selection==='value')result.committedText=[...trigger.selectedOptions].map(o=>o.label).join(', ');\n  }else if(hidden){\n    result.selection=hidden.value!==''?'value':hidden.hasAttribute('value')?'unknown':'empty';result.selectionEvidence='backing-input';\n    if(result.selection==='value' && text)result.committedText=text.slice(0,2000);\n    if(!label && result.selection==='empty' && text){result.label=text.slice(0,200);result.labelSource='empty-display';}\n  }\n  if(['INPUT','TEXTAREA'].includes(trigger.tagName) && trigger.type!=='hidden'){\n    if(!backing || !hidden.value || panels.some(visible))result.queryText=trigger.value;\n    if(!label && trigger.placeholder){result.label=clean(trigger.placeholder).slice(0,200);result.labelSource='placeholder';}\n  }\n  if(panels.length)result.panelVisible=panels.some(visible);\n  if(trigger.hasAttribute('aria-expanded'))result.expanded=trigger.getAttribute('aria-expanded')==='true';\n  else if(panels.length)result.expanded=result.panelVisible;\n  return result;\n}";

package/dist/goal/picker-state.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import type { BrowserElementRef } from "@roll-agent/browser";
+import type { GoalSnapshot } from "./observation.ts";
+declare const FieldSchema: z.ZodObject<Pick<{
+    part: z.ZodEnum<["trigger", "option"]>;
+    relationship: z.ZodEnum<["aria", "local-dom", "unknown"]>;
+    triggerPath: z.ZodOptional<z.ZodString>;
+    panelPaths: z.ZodArray<z.ZodString, "many">;
+    label: z.ZodOptional<z.ZodString>;
+    labelSource: z.ZodOptional<z.ZodEnum<["label", "placeholder", "empty-display"]>>;
+    expanded: z.ZodOptional<z.ZodBoolean>;
+    panelVisible: z.ZodOptional<z.ZodBoolean>;
+    selection: z.ZodEnum<["empty", "value", "unknown"]>;
+    selectionEvidence: z.ZodEnum<["native-select", "backing-input", "unknown"]>;
+    committedText: z.ZodOptional<z.ZodString>;
+    queryText: z.ZodOptional<z.ZodString>;
+    optionText: z.ZodOptional<z.ZodString>;
+    optionLabel: z.ZodOptional<z.ZodString>;
+    optionPath: z.ZodOptional<z.ZodString>;
+    optionSelected: z.ZodOptional<z.ZodBoolean>;
+}, "label" | "expanded" | "selection" | "relationship" | "panelVisible" | "selectionEvidence" | "committedText" | "queryText"> & {
+    id: z.ZodString;
+    triggerRef: z.ZodOptional<z.ZodString>;
+    labelOrigin: z.ZodEnum<["dom-label", "dom-placeholder", "dom-empty-display", "earlier-dom-label", "earlier-dom-placeholder", "earlier-dom-empty-display", "unknown"]>;
+    optionRefs: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    selection: "value" | "unknown" | "empty";
+    relationship: "unknown" | "aria" | "local-dom";
+    selectionEvidence: "unknown" | "native-select" | "backing-input";
+    labelOrigin: "unknown" | "dom-label" | "dom-placeholder" | "dom-empty-display" | "earlier-dom-label" | "earlier-dom-placeholder" | "earlier-dom-empty-display";
+    optionRefs: string[];
+    label?: string | undefined;
+    expanded?: boolean | undefined;
+    panelVisible?: boolean | undefined;
+    committedText?: string | undefined;
+    queryText?: string | undefined;
+    triggerRef?: string | undefined;
+}, {
+    id: string;
+    selection: "value" | "unknown" | "empty";
+    relationship: "unknown" | "aria" | "local-dom";
+    selectionEvidence: "unknown" | "native-select" | "backing-input";
+    labelOrigin: "unknown" | "dom-label" | "dom-placeholder" | "dom-empty-display" | "earlier-dom-label" | "earlier-dom-placeholder" | "earlier-dom-empty-display";
+    optionRefs: string[];
+    label?: string | undefined;
+    expanded?: boolean | undefined;
+    panelVisible?: boolean | undefined;
+    committedText?: string | undefined;
+    queryText?: string | undefined;
+    triggerRef?: string | undefined;
+}>;
+declare const PartSchema: z.ZodObject<Pick<{
+    part: z.ZodEnum<["trigger", "option"]>;
+    relationship: z.ZodEnum<["aria", "local-dom", "unknown"]>;
+    triggerPath: z.ZodOptional<z.ZodString>;
+    panelPaths: z.ZodArray<z.ZodString, "many">;
+    label: z.ZodOptional<z.ZodString>;
+    labelSource: z.ZodOptional<z.ZodEnum<["label", "placeholder", "empty-display"]>>;
+    expanded: z.ZodOptional<z.ZodBoolean>;
+    panelVisible: z.ZodOptional<z.ZodBoolean>;
+    selection: z.ZodEnum<["empty", "value", "unknown"]>;
+    selectionEvidence: z.ZodEnum<["native-select", "backing-input", "unknown"]>;
+    committedText: z.ZodOptional<z.ZodString>;
+    queryText: z.ZodOptional<z.ZodString>;
+    optionText: z.ZodOptional<z.ZodString>;
+    optionLabel: z.ZodOptional<z.ZodString>;
+    optionPath: z.ZodOptional<z.ZodString>;
+    optionSelected: z.ZodOptional<z.ZodBoolean>;
+}, "part" | "optionText" | "optionLabel" | "optionSelected"> & {
+    fieldId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    part: "option" | "trigger";
+    optionText?: string | undefined;
+    optionLabel?: string | undefined;
+    optionSelected?: boolean | undefined;
+    fieldId?: string | undefined;
+}, {
+    part: "option" | "trigger";
+    optionText?: string | undefined;
+    optionLabel?: string | undefined;
+    optionSelected?: boolean | undefined;
+    fieldId?: string | undefined;
+}>;
+export type PickerField = z.infer<typeof FieldSchema>;
+export type PickerPart = z.infer<typeof PartSchema>;
+export type PickerState = {
+    fields: PickerField[];
+    parts: Record<string, PickerPart>;
+};
+/** Observation memory, not a plan or approval ledger. Never infer a relation from proximity. */
+export declare function createPickerMemory(): {
+    observe(snapshot: GoalSnapshot): PickerState;
+};
+export declare function pickerActionLabel(ref: Pick<BrowserElementRef, "ref" | "role" | "name">, state: PickerState, operation?: string): string;
+export {};

package/dist/goal/reachability.d.ts

@@ -0,0 +1,2 @@
+/** Fixed read-only geometry probe. Revealing still uses the native driver's CDP path. */
+export declare const INSPECT_REACHABILITY = "function(el,origins) {\n  let revealViaScroll=false;\n  const result=(availability)=>({availability,...(availability==='offscreen' && revealViaScroll?{revealViaScroll:true}:{})});\n  const transformed=s=>s.transform!=='none' || s.perspective!=='none' || (s.translate && s.translate!=='none') || (s.rotate && s.rotate!=='none') || (s.scale && s.scale!=='none') || (s.zoom && s.zoom!=='normal' && Number(s.zoom)!==1);\n  const layer=(node,view)=>{for(let p=node;p;p=p.parentElement){if(p.matches('dialog[open],[role=\"dialog\"],[aria-modal=\"true\"]'))return p;const s=view.getComputedStyle(p);if(s.position==='fixed' || s.position==='sticky')return p;}return null;};\n  const modal=node=>node && (node.matches('dialog[open],[role=\"dialog\"],[aria-modal=\"true\"]') || Boolean(node.closest('dialog[open],[role=\"dialog\"],[aria-modal=\"true\"]')));\n  const edgeLayer=(cover,ownLayer,view)=>{\n    if(!cover || cover===ownLayer || modal(cover))return false;\n    const cr=cover.getBoundingClientRect();\n    return (cr.height<view.innerHeight/2 && (cr.top<=1 || cr.bottom>=view.innerHeight-1)) || (cr.width<view.innerWidth/2 && (cr.left<=1 || cr.right>=view.innerWidth-1));\n  };\n  const bounds=(node)=>{const r=node.getBoundingClientRect();return {left:r.left+node.clientLeft,top:r.top+node.clientTop,right:r.left+node.clientLeft+node.clientWidth,bottom:r.top+node.clientTop+node.clientHeight};};\n  const room=(node,axis,direction)=>{const offset=axis==='x'?node.scrollLeft:node.scrollTop,max=axis==='x'?node.scrollWidth-node.clientWidth:node.scrollHeight-node.clientHeight;return direction<0?offset>1:offset<max-1;};\n  try {\n    let view=el.ownerDocument.defaultView,node=el;\n    if(!view || !origins.includes(view.location.origin))return result('unavailable');\n    const r=el.getBoundingClientRect();let point={x:r.left+r.width/2,y:r.top+r.height/2},reveal=false;\n    for(let depth=0;depth<33;depth++){\n      if(depth===32 || !origins.includes(view.location.origin))return result('unavailable');\n      const doc=node.ownerDocument,root=doc.scrollingElement,ownLayer=layer(node,view);\n      const activeModal=[...doc.querySelectorAll('dialog[open],[aria-modal=\"true\"]')].find(p=>{const s=view.getComputedStyle(p);return p.getClientRects().length && s.display!=='none' && s.visibility==='visible' && s.opacity!=='0' && !p.contains(node);});\n      if(activeModal)return result('covered');\n      const viewport={left:0,top:0,right:view.innerWidth,bottom:view.innerHeight};\n      let scope=node,visible={...viewport},localReveal=false;\n      const movable=[];\n      for(let p=node;p;p=p.parentElement){\n        const s=view.getComputedStyle(p);\n        if(transformed(s))return result('unavailable');\n        if(s.display==='none' || s.visibility!=='visible' || s.opacity==='0' || p.hasAttribute('inert'))return result('covered');\n        if(p===node || p===root || p===doc.body)continue;\n        const b=bounds(p);\n        const axes=[['x','overflowX','left','right'],['y','overflowY','top','bottom']];\n        for(const [axis,overflow,low,high] of axes){\n          if(!/^(auto|scroll|hidden|clip)$/.test(s[overflow]))continue;\n          const scrollable=/^(auto|scroll)$/.test(s[overflow]);\n          if(scrollable)movable.push({node:p,axis,b});\n          if(point[axis]<b[low] || point[axis]>=b[high]){\n            if(!scrollable || !room(p,axis,point[axis]<b[low]?-1:1))return result('covered');\n            point[axis]=Math.max(b[low]+1,Math.min(b[high]-2,point[axis]));scope=p;localReveal=true;visible={left:Math.max(0,b.left),top:Math.max(0,b.top),right:Math.min(view.innerWidth,b.right),bottom:Math.min(view.innerHeight,b.bottom)};\n          }\n          visible[low]=Math.max(visible[low],b[low]);visible[high]=Math.min(visible[high],b[high]);\n        }\n      }\n      const rootStyle=root && view.getComputedStyle(root),bodyStyle=doc.body && view.getComputedStyle(doc.body);\n      for(const [axis,overflow,low,high] of [['x','overflowX','left','right'],['y','overflowY','top','bottom']]){\n        const scrollable=root && !ownLayer && ![rootStyle?.[overflow],bodyStyle?.[overflow]].some(value=>value==='hidden' || value==='clip');\n        if(scrollable)movable.push({node:root,axis,b:viewport});\n        if(point[axis]<viewport[low] || point[axis]>=viewport[high]){\n          if(!scrollable || !room(root,axis,point[axis]<viewport[low]?-1:1))return result('covered');\n          point[axis]=Math.max(viewport[low]+1,Math.min(viewport[high]-2,point[axis]));scope=root;localReveal=true;visible={...viewport};\n        }\n      }\n      const same=(hit)=>hit && (hit===node || node.contains(hit));\n      const exposed=(hit,container)=>{\n        if(!hit || !(hit===container || container.contains(hit)))return false;\n        const hitLayer=layer(hit,view);\n        return !hitLayer || hitLayer===ownLayer;\n      };\n      const sample=(container,region)=>{\n        if(region.right-region.left<4 || region.bottom-region.top<4)return null;\n        for(const fy of [0.5,0.25,0.75,0.05,0.95])for(const fx of [0.5,0.25,0.75,0.05,0.95]){\n          const p={x:region.left+(region.right-region.left)*fx,y:region.top+(region.bottom-region.top)*fy};\n          if(exposed(doc.elementFromPoint(p.x,p.y),container))return p;\n        }\n        return null;\n      };\n      const hit=doc.elementFromPoint(point.x,point.y);\n      if(localReveal){\n        if(!exposed(hit,scope)){\n          if(!edgeLayer(hit && layer(hit,view),ownLayer,view))return result('covered');\n          revealViaScroll=true;\n        }\n        const probe=exposed(hit,scope)?point:sample(scope,visible);\n        if(!probe)return result('covered');point=probe;reveal=true;\n      }else if(!same(hit)){\n        // A small edge-docked fixed/sticky toolbar may cover a scrollable target.\n        // Dialogs, central overlays and full-screen layers are never reveal routes.\n        const cover=hit && layer(hit,view),cr=cover && cover.getBoundingClientRect();\n        if(!edgeLayer(cover,ownLayer,view))return result('covered');\n        let probe=null;\n        for(const candidate of movable){\n          const axis=candidate.axis,coordinate=axis==='x'?point.x:point.y;\n          const start=axis==='x'?cr.left:cr.top,end=axis==='x'?cr.right:cr.bottom;\n          if(coordinate<start || coordinate>=end)continue;\n          const towardStart=start>=(axis==='x'?view.innerWidth:view.innerHeight)/2;\n          if(!room(candidate.node,axis,towardStart?1:-1))continue;\n          const region={left:Math.max(visible.left,candidate.b.left),top:Math.max(visible.top,candidate.b.top),right:Math.min(visible.right,candidate.b.right),bottom:Math.min(visible.bottom,candidate.b.bottom)};\n          if(axis==='y'){if(towardStart)region.bottom=Math.min(region.bottom,cr.top);else region.top=Math.max(region.top,cr.bottom);}\n          else if(towardStart)region.right=Math.min(region.right,cr.left);else region.left=Math.max(region.left,cr.right);\n          probe=sample(candidate.node,region);if(probe)break;\n        }\n        if(!probe)return result('covered');point=probe;reveal=true;revealViaScroll=true;\n      }\n      if(view===view.top)return result(reveal?'offscreen':'ready');\n      const owner=view.frameElement,parent=owner?.ownerDocument.defaultView;\n      if(!owner || !parent || !origins.includes(parent.location.origin))return result('unavailable');\n      const box=owner.getBoundingClientRect();point={x:point.x+box.left+owner.clientLeft,y:point.y+box.top+owner.clientTop};\n      node=owner;view=parent;\n    }\n  }catch{return result('unavailable');}\n  return result('unavailable');\n}";

package/dist/goal/task-evidence.d.ts

@@ -0,0 +1,33 @@
+import type { ReadDocument, ReadTask, TaskProgress } from "./task-progress.ts";
+export declare function evidenceCandidates(documents: readonly ReadDocument[]): {
+    key: string;
+    doc: {
+        url: string;
+        frameId: string;
+        panelsComplete: boolean;
+        observedAt: string;
+        regions: {
+            id: string;
+            truncated: boolean;
+            name: string;
+            text: string;
+            kind: "content" | "panel";
+        }[];
+    };
+    region: {
+        id: string;
+        truncated: boolean;
+        name: string;
+        text: string;
+        kind: "content" | "panel";
+    };
+    spans: {
+        id: string;
+        text: string;
+        start: number;
+        end: number;
+    }[];
+}[];
+export type EvidenceCandidate = ReturnType<typeof evidenceCandidates>[number];
+/** Commit one complete, same-observation packet. Never stitch fields from different records. */
+export declare function commitEvidence(progress: TaskProgress, contract: ReadTask, candidate: EvidenceCandidate, selected: readonly string[], observationId: string, documentId: string): boolean;

package/dist/goal/task-freshness.d.ts

@@ -0,0 +1,86 @@
+import type { BrowserElementRef } from "@roll-agent/browser";
+import { z } from "zod";
+import type { GoalControl, GoalSnapshot } from "./observation.ts";
+export declare const ActionDependenciesSchema: z.ZodObject<{
+    documentId: z.ZodNullable<z.ZodString>;
+    browserInstance: z.ZodNullable<z.ZodString>;
+    pageId: z.ZodNullable<z.ZodString>;
+    targetIdentity: z.ZodString;
+    relatedIdentities: z.ZodArray<z.ZodString, "many">;
+    reusable: z.ZodBoolean;
+    unavailableReasons: z.ZodArray<z.ZodString, "many">;
+    notedCoverageWarnings: z.ZodArray<z.ZodString, "many">;
+    fingerprint: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    browserInstance: string | null;
+    pageId: string | null;
+    documentId: string | null;
+    fingerprint: string;
+    targetIdentity: string;
+    relatedIdentities: string[];
+    reusable: boolean;
+    unavailableReasons: string[];
+    notedCoverageWarnings: string[];
+}, {
+    browserInstance: string | null;
+    pageId: string | null;
+    documentId: string | null;
+    fingerprint: string;
+    targetIdentity: string;
+    relatedIdentities: string[];
+    reusable: boolean;
+    unavailableReasons: string[];
+    notedCoverageWarnings: string[];
+}>;
+export type ActionDependencies = z.infer<typeof ActionDependenciesSchema>;
+/** Position guides visual ordering, but movement alone is not a semantic change.
+ * Availability includes live hit testing and must remain part of every guard.
+ * Keep all other metadata, including ownership paths and constraint provenance.
+ */
+export declare function semanticGoalControl(control: GoalControl): Omit<GoalControl, "position">;
+/** Capture only the current action's observed dependencies, never the whole page text.
+ * An incomplete observation is explicitly non-reusable. Callers must re-observe
+ * or escalate; a matching fingerprint never replaces the native dispatch guard.
+ */
+export declare function captureActionDependencies(snapshot: GoalSnapshot, target: BrowserElementRef, relatedIdentities?: readonly string[]): ActionDependencies;
+export declare function actionDependenciesMatch(expected: ActionDependencies, fresh: GoalSnapshot): boolean;
+export declare const FormCompletionDependenciesSchema: z.ZodObject<{
+    documentId: z.ZodNullable<z.ZodString>;
+    browserInstance: z.ZodNullable<z.ZodString>;
+    pageId: z.ZodNullable<z.ZodString>;
+    controlIdentities: z.ZodArray<z.ZodString, "many">;
+    fieldCount: z.ZodNumber;
+    reusable: z.ZodBoolean;
+    unavailableReasons: z.ZodArray<z.ZodString, "many">;
+    notedCoverageWarnings: z.ZodArray<z.ZodString, "many">;
+    fingerprint: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    browserInstance: string | null;
+    pageId: string | null;
+    documentId: string | null;
+    fingerprint: string;
+    reusable: boolean;
+    unavailableReasons: string[];
+    notedCoverageWarnings: string[];
+    controlIdentities: string[];
+    fieldCount: number;
+}, {
+    browserInstance: string | null;
+    pageId: string | null;
+    documentId: string | null;
+    fingerprint: string;
+    reusable: boolean;
+    unavailableReasons: string[];
+    notedCoverageWarnings: string[];
+    controlIdentities: string[];
+    fieldCount: number;
+}>;
+export type FormCompletionDependencies = z.infer<typeof FormCompletionDependenciesSchema>;
+/** For a prepared form's final review only. This is an observation-change guard,
+ * not a completion oracle. Preserve every observed control and AX/context error;
+ * exclude only the independent pageText blob, which mixes unrelated clocks with
+ * page content. Non-form or incomplete observations must use the caller's global
+ * fallback. In particular, this cannot certify text absent from AX/DOM metadata.
+ */
+export declare function captureFormCompletionDependencies(snapshot: GoalSnapshot): FormCompletionDependencies;
+export declare function formCompletionDependenciesMatch(expected: FormCompletionDependencies, fresh: GoalSnapshot): boolean;

package/dist/goal/task-loop.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserOperateInput, BrowserOperateOutput } from "./contracts.ts";
+import type { DecisionProvider } from "./decisions.ts";
+import type { GoalDriver } from "./loop.ts";
+/** Interaction only: the selected engine decides; Roll owns preparation and final verification. */
+export declare function runBrowserTask(input: BrowserOperateInput, driver: GoalDriver, decide: DecisionProvider, signal: AbortSignal): Promise<BrowserOperateOutput>;

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

@@ -0,0 +1,5 @@
+import type { NativeCdpController } from "@roll-agent/browser";
+import type { GoalSnapshot } from "./observation.ts";
+export declare const READ_GOAL_TEXT = "function(origins, limit, captureEvidence) {\n  const doc=this.ownerDocument || this, view=doc && doc.defaultView;\n  if(!view || !origins.includes(view.location.origin)) return {text:'',truncated:true};\n  if(!doc.body)return {text:'',truncated:false};\n  const visible=el=>el.checkVisibility({checkOpacity:true,checkVisibilityCSS:true}) && [...el.getClientRects()].some(r=>r.width>0 && r.height>0 && r.bottom>0 && r.top<view.innerHeight && r.right>0 && r.left<view.innerWidth);\n  const text=el=>(el?.innerText || el?.textContent || '').replace(/\\s+/g,' ').trim();\n  const panels=[...doc.querySelectorAll('dialog[open],[role=\"dialog\"],[aria-modal=\"true\"],[class*=\"dialog\"],[class*=\"modal\"],[class*=\"popup\"]')].filter(el=>{\n    if(!visible(el))return false;\n    const style=view.getComputedStyle(el);\n    return el.matches('dialog[open],[role=\"dialog\"],[aria-modal=\"true\"]') || ['fixed','absolute'].includes(style.position) && /(?:^|[\\s_-])(dialog|modal|popup)(?:[\\s_-]|$)/i.test(String(el.className));\n  });\n  const pageState={\n    panels:panels.filter(el=>!panels.some(parent=>parent!==el && parent.contains(el))).slice(0,16).map(el=>(el.getAttribute('aria-label') || text(el.querySelector('h1,h2,h3,h4,[role=\"heading\"],[class*=\"title\"]')) || text(el) || 'Unlabelled visible panel').slice(0,400)),\n    selectedTabs:[...doc.querySelectorAll('[role=\"tab\"][aria-selected=\"true\"],[class*=\"tab\"].active,[class*=\"tab\"].selected,[class*=\"tab\"][aria-current=\"page\"]')].filter(visible).slice(0,32).map(el=>text(el).slice(0,200)),\n    busy:[...doc.querySelectorAll('[aria-busy=\"true\"],[role=\"progressbar\"]')].some(visible)\n  };\n  const pathOf=el=>{const parts=[];for(let p=el;p&&p!==doc.body;p=p.parentElement){let n=1;for(let q=p.previousElementSibling;q;q=q.previousElementSibling)if(q.tagName===p.tagName)n++;parts.unshift(p.tagName.toLowerCase()+':'+n)}return parts.join('/')};\n  const outerPanels=panels.filter(el=>!panels.some(parent=>parent!==el&&parent.contains(el)));\n  const contentRegions=!captureEvidence ? [] : outerPanels.length ? outerPanels : [...doc.querySelectorAll('main,article,[role=\"main\"]')].filter(visible).filter(el=>!el.parentElement?.closest('main,article,[role=\"main\"]'));\n  const readDocument=captureEvidence ? {url:doc.location.href,panelsComplete:outerPanels.length<=4,\n    regions:contentRegions.slice(0,4).map(el=>{const raw=el.innerText||'';return {id:pathOf(el),name:(el.getAttribute('aria-label')||text(el.querySelector('h1,h2,h3,h4,[role=\"heading\"],[class*=\"title\"]'))||'Unlabelled content region').slice(0,400),kind:outerPanels.includes(el)?'panel':'content',text:raw.slice(0,16000),truncated:raw.length>16000}})} : undefined;\n  const walker=doc.createTreeWalker(doc.body,4), range=doc.createRange(), parts=[];\n  let node, length=0, visited=0;\n  while((node=walker.nextNode()) && visited++<5000){\n    const parent=node.parentElement, text=(node.textContent||'').replace(/\\s+/g,' ').trim();\n    if(!text || !parent || parent.closest('script,style,noscript,template,[aria-hidden=\"true\"]'))continue;\n    if(!parent.checkVisibility({checkOpacity:true,checkVisibilityCSS:true}))continue;\n    range.selectNodeContents(node);const r=range.getBoundingClientRect();\n    if(!r.width || !r.height || r.bottom<=0 || r.top>=view.innerHeight || r.right<=0 || r.left>=view.innerWidth)continue;\n    parts.push(text.slice(0,Math.max(0,limit-length)));length+=text.length+1;\n    if(length>=limit)return {text:parts.join('\\n').slice(0,limit),truncated:true,pageState,...(readDocument?{readDocument}:{})};\n  }\n  return {text:parts.join('\\n').slice(0,limit),truncated:visited>=5000,pageState,...(readDocument?{readDocument}:{})};\n}";
+/** Text has its own budget; static layout must never consume the control budget. */
+export declare function attachTaskText(controller: Pick<NativeCdpController, "resolveBackendNode" | "callFunctionOnObject" | "releaseObject">, snapshot: GoalSnapshot, origins: readonly string[], signal: AbortSignal, captureEvidence?: boolean): Promise<GoalSnapshot>;

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

@@ -0,0 +1,174 @@
+import type { ExecutionContext } from "./execution-context.ts";
+import type { TaskProgress } from "./task-progress.ts";
+import type { BrowserAxNode, BrowserElementRef } from "@roll-agent/browser";
+import type { BrowserOperateInput, BrowserOperateOutput } from "./contracts.ts";
+import type { DecisionRequest } from "./decisions.ts";
+import type { PickerState } from "./picker-state.ts";
+import type { GoalSnapshot } from "./observation.ts";
+export declare const taskNodes: (nodes: readonly BrowserAxNode[]) => BrowserAxNode[];
+export declare function taskControlIdentity(ref: BrowserElementRef): string;
+export declare function taskElements(snapshot: GoalSnapshot): {
+    ref: string;
+    identity: string;
+    role: string;
+    name: string;
+    disabled: boolean;
+    readonly: string | number | boolean | undefined;
+    value: string | undefined;
+    valueKind: string;
+    displayText: string | undefined;
+    checked: string | number | boolean | undefined;
+    selected: string | number | boolean | undefined;
+    fieldLabel: string | undefined;
+    pickerIdentity: string | undefined;
+    readable: boolean | undefined;
+    peerGroup: {
+        count: number;
+        key: string;
+        position: number;
+    } | undefined;
+    pickerOwnerPath: string | undefined;
+    pickerOptionPath: string | undefined;
+    pickerOptionLabel: string | undefined;
+    required: boolean | undefined;
+    requiredSource: "html" | "aria" | "label-required" | "label-optional" | undefined;
+    constraints: {
+        multiple?: boolean | undefined;
+        pattern?: string | undefined;
+        min?: string | undefined;
+        max?: string | undefined;
+        step?: string | undefined;
+        minlength?: string | undefined;
+        maxlength?: string | undefined;
+    } | undefined;
+    position: {
+        left: number;
+        top: number;
+    } | undefined;
+    scrollContainerPaths: string[] | undefined;
+    revealViaScroll: boolean | undefined;
+    inputType: string | undefined;
+    expanded: string | number | boolean | undefined;
+    validationErrors: string[] | undefined;
+    invalid: string | number | boolean | undefined;
+    context: string[];
+    availability: "hidden" | "ready" | "offscreen" | "covered" | "unavailable";
+    editable: boolean | undefined;
+    layer: string | undefined;
+    modal: boolean | undefined;
+    nativeSelect: boolean | undefined;
+    options: {
+        value: string;
+        label: string;
+        disabled: boolean;
+        selected: boolean;
+    }[] | undefined;
+    optionsTruncated: boolean | undefined;
+}[];
+export declare function taskFingerprint(snapshot: GoalSnapshot): string;
+export declare function taskState(input: BrowserOperateInput, snapshot: GoalSnapshot, history: BrowserOperateOutput["steps"], guidance?: string, resolvedValues?: NonNullable<BrowserOperateOutput["resolvedValues"]>, pickers?: PickerState): {
+    originalGoal: string;
+    pickerFields: {
+        id: string;
+        selection: "value" | "unknown" | "empty";
+        relationship: "unknown" | "aria" | "local-dom";
+        selectionEvidence: "unknown" | "native-select" | "backing-input";
+        labelOrigin: "unknown" | "dom-label" | "dom-placeholder" | "dom-empty-display" | "earlier-dom-label" | "earlier-dom-placeholder" | "earlier-dom-empty-display";
+        optionRefs: string[];
+        label?: string | undefined;
+        expanded?: boolean | undefined;
+        panelVisible?: boolean | undefined;
+        committedText?: string | undefined;
+        queryText?: string | undefined;
+        triggerRef?: string | undefined;
+    }[];
+    activePanels: string[];
+    selectedTabs: string[] | undefined;
+    pageBusy: boolean | undefined;
+    valueSemantics: string;
+    delegatedDecisions: string[];
+    pageText: string;
+    pageTextTruncated: boolean | undefined;
+    facts: {
+        [k: string]: {
+            name: string;
+            text: string;
+            fullLength: number;
+        };
+    };
+    elements: {
+        value: string | undefined;
+        fullLength: number | undefined;
+        sourceValueMatches: string[];
+        writtenValueMatches: string[];
+        picker?: {
+            part: "option" | "trigger";
+            optionText?: string | undefined;
+            optionLabel?: string | undefined;
+            optionSelected?: boolean | undefined;
+            fieldId?: string | undefined;
+        };
+        displayText?: string;
+        valueKind: string;
+        options?: {
+            disabled?: boolean;
+            selected?: boolean;
+            label: string;
+        }[];
+        modal?: boolean;
+        layer?: string;
+        context: string[];
+        availability?: "hidden" | "offscreen" | "covered" | "unavailable";
+        invalid?: string | number | true;
+        validationErrors?: string[];
+        expanded?: string | number | boolean;
+        inputType?: string;
+        position?: {
+            left: number;
+            top: number;
+        };
+        constraints?: {
+            multiple?: boolean | undefined;
+            pattern?: string | undefined;
+            min?: string | undefined;
+            max?: string | undefined;
+            step?: string | undefined;
+            minlength?: string | undefined;
+            maxlength?: string | undefined;
+        };
+        requiredSource?: "html" | "aria" | "label-required" | "label-optional";
+        required?: boolean;
+        fieldLabel?: string;
+        selected?: string | number | boolean;
+        checked?: string | number | boolean;
+        nativeSelect?: boolean;
+        editable?: boolean;
+        readonly?: boolean;
+        disabled?: boolean;
+        ref: string;
+        role: string;
+        name: string;
+        frame: number;
+    }[];
+    contexts: Record<string, string>;
+    resolvedValues: {
+        id: string;
+        field: string;
+        source: "selected" | "supplied" | "derived" | "generated";
+        sourceIds: string[];
+        text: string;
+        fullLength: number;
+    }[];
+    recentActions: {
+        operation: string;
+        target: string | undefined;
+        valueName: string | undefined;
+        executed: boolean;
+        error: string | undefined;
+    }[];
+    guidance: string;
+    forbiddenControlNames: string[];
+    truncated: boolean;
+    coverageWarnings: string[] | undefined;
+};
+export declare function buildTaskDecisionRequest(input: BrowserOperateInput, snapshot: GoalSnapshot, history: BrowserOperateOutput["steps"], guidance?: string, suppressedClicks?: ReadonlySet<string>, resolvedValues?: NonNullable<BrowserOperateOutput["resolvedValues"]>, pickers?: PickerState, progress?: TaskProgress, execution?: ExecutionContext): DecisionRequest;

package/dist/goal/task-progress-policy.d.ts

@@ -0,0 +1,25 @@
+import type { DecisionRequest } from "./decisions.ts";
+import type { GoalSnapshot } from "./observation.ts";
+import type { ReadTask, TaskProgress } from "./task-progress.ts";
+export declare function progressSummary(progress: TaskProgress, contract: ReadTask): {
+    taskRunId: string;
+    phase: "collect" | "return" | "done";
+    target: string;
+    captureView: string;
+    outputs: string[];
+    captured: {
+        field: string;
+        evidenceId: string;
+        text: string;
+    }[];
+    missing: string[];
+    terminal: {
+        view: string;
+        selectedTab?: string | undefined;
+    };
+    remaining: string;
+};
+/** All questions consume the SAME observed state; branches never read one another's answers. */
+export declare function withTaskProgress(request: DecisionRequest, snapshot: GoalSnapshot, contract: ReadTask | undefined, progress: TaskProgress | undefined): DecisionRequest;
+export declare function acceptProgressEvidence(progress: TaskProgress, contract: ReadTask, snapshot: GoalSnapshot, choices: Record<string, string>): boolean;
+export declare function terminalObservationMatches(progress: TaskProgress, contract: ReadTask, snapshot: GoalSnapshot): boolean;