Give clickRef to prima only, the one agent whose context carries refs

[DavertMik]

PR #110 stated the rule and the squashed commit broke it:

A tool's schema is shared with every caller, and Tester never receives ref-bearing snapshots, so it must not be shown a ref parameter it could only fill by inventing one. The ref tools live in the boat that uses them.

What landed instead put clickRef in createCodeceptJSTools — shared with Tester, Captain, Rerunner and Driller — and added interactiveAriaWithRefs so the Tester began receiving ref-bearing snapshots after all. There is no boat/prima/src/tools.ts.

Why it mattered in the Tester

ACTION_TOOLS (src/ai/tester.ts:43) never listed clickRef, so a successful ref-click was invisible to shouldStopForStalledExecution (:458) and prepareInstructionsForNextStep (:484) never offered it. The locator rule told the model to prefer clickRef while the loop scored using it as no progress.

Seen in a live session: after a modal was dismissed, the Tester filled the title via clickRef + type, that worked, and the stall detector ended the test three iterations later having counted none of it. The recorded step was I.usePlaywrightTo("click Title textbox", fn()) — a Playwright closure in what is meant to be replayable CodeceptJS.

Changes

• src/ai/tools.ts — clickRef extracted into createRefTools({explorer, stateManager}, task), mirroring the createIframeTools precedent in the same file. click() and form() no longer name it: a shared description must not reference a tool the caller does not have.
• src/ai/rules.ts — ref paragraph out of locatorPriorityRule, which is shared by Researcher, Tester, Navigator, Captain, Rerunner, Driller and prima. Prima states it in its own <targets> / <targets_first>.
• src/ai/tester.ts — both call sites back to currentState.getInteractiveARIA(), method deleted. Exact revert of the prima check: run a scenario end to end and report what it proved #110 hunk.
• boat/prima/src/prima.ts:151 — spreads createRefTools(deps, task).
• tests/unit/tools.test.ts — guards the split so it cannot drift back.

Invariant

Refs in context if and only if a ref tool is present.

Agent	refs	clickRef
prima	refAriaSnapshot() (prima.ts:918)	yes (prima.ts:151)
Tester / Captain / Rerunner / Navigator	no	no
Driller	calls annotatePageElements but discards it (driller.ts:188-198)	no

tests/integration/prima-do.test.ts:140 already asserted prima keeps clickRef, and :108-109 drive real calls — still passing.

Verification

bun test tests/unit/ 1024 pass · bun test tests/integration/ 81 pass · lint clean · format clean.

Branched off main rather than the current working branch so it does not stack behind #129. CHANGELOG deliberately untouched.

Not in scope

describeRef (src/ai/tools.ts) still cannot name an empty text input — no aria-label, no innerText, empty value — so it returns null and prima records the unreplayable usePlaywrightTo(..., fn()) instead of I.click(...). Falling back to placeholder and the associated <label for> would fix the whole class.

🤖 Generated with Claude Code

[DenysKuchma]

Fix test