handhold-sdk 1.0.0

package/src/agent/VENDOR.md

@@ -0,0 +1,203 @@
+# VENDOR — trusted-page-agent (Handhold action engine)
+
+This directory (`sdk/src/agent/`) is a **vendored drop** of the security-audited
+`trusted-page-agent` engine. It is the safe action layer for Handhold's
+"Do it for me" mode. Treat the engine source as audited code: change it **only**
+through documented patches recorded in this file, so future upstream syncs stay
+possible.
+
+## Origin
+
+| Field | Value |
+|---|---|
+| Upstream package | `trusted-page-agent` |
+| Version | `0.1.0` (frozen as the vendor drop / "P0" in the master plan) |
+| Source in this repo | `handhold-agent-integration/vendor/trusted-page-agent/` |
+| Upstream commit | none — delivered as a plain source drop (no `.git`); provenance is the security audit in the drop's `SECURITY.md` (alibaba/page-agent @ main, audited 2026-07-05) |
+| Vendored on | 2026-07-06 (task H1) |
+| Engine source checksum | `find . -name '*.js' -exec md5 -q {} \; | sort | md5` → `75cc24f480489f8ca90e37513372b961` |
+
+The security guarantees this engine must preserve are documented in the drop's
+`SECURITY.md`. The load-bearing ones for Handhold: no model-authored code ever
+executes (no `eval` / `new Function` / script-tool); actions only on allowlisted
+origins; sensitive actions fail closed on human confirm; PII redacted before
+transmission; every decision audited.
+
+## What was copied
+
+- `handhold-agent-integration/vendor/trusted-page-agent/src/` → `sdk/src/agent/`
+  (domTree, serializer, redact, actions, utils, tools, prompts, AgentLoop,
+  controller, PolicyGuard, connector, ChatWidget, index).
+- `handhold-agent-integration/vendor/trusted-page-agent/test/` → `sdk/test/agent/`.
+
+At H1 the engine **source `.js` files were byte-for-byte identical** to the drop
+(verified by matching md5 above). Since then the only engine-source change is
+patch #5 below (`dom/serializer.js`, task H5); every other file remains
+byte-identical to the drop. As of H5 the SDK imports the engine via
+`sdk/src/agent-mode/AgentMode.js` (lazy `import()` bundled eagerly by webpack).
+
+## Deviations from the drop (the full patch list)
+
+Every change made while vendoring, so an upstream re-sync is a mechanical replay:
+
+1. **Added `sdk/src/agent/package.json`** = `{"type":"module"}`.
+   Why: the engine is authored as ESM. The root SDK is CommonJS (webpack config
+   uses `require`), so we cannot set `"type":"module"` at the SDK root. A nested
+   package.json scopes ESM to this directory only — Node resolves module type
+   from the nearest package.json, and webpack/babel bundle ESM regardless.
+   **Not an engine-source change.**
+
+2. **Added `sdk/test/agent/package.json`** = `{"type":"module"}`. Same reason,
+   so `node --test` treats the relocated tests as ESM.
+
+3. **Rewrote test import paths** in `sdk/test/agent/*.test.js`:
+   `'../src/...'` → `'../../src/agent/...'`. Purely mechanical — tests moved from
+   `<drop>/test/` (sibling of `src/`) to `sdk/test/agent/` (two levels from
+   `sdk/src/agent/`). No test logic changed (verified by `diff`: only the
+   `import ... from` lines differ).
+
+4. **Added `sdk/test/agent/invariants.test.js`** — a grep-invariant test that
+   fails if `eval(` / `new Function(` / `.innerHTML` / `document.write(` /
+   dynamic `import(` appears in executable code under `sdk/src/agent/` (comments
+   and JSDoc `import()` type annotations are stripped first). The drop shipped
+   this guarantee as prose in `SECURITY.md` but **not** as an automated check;
+   this test codifies it so the invariant "travels with the vendor drop" and
+   stays green in CI. Proven to have teeth (fails on an injected `eval`/`innerHTML`
+   probe). **Not an engine-source change** — it guards the engine, does not modify it.
+
+5. **Patched `sdk/src/agent/dom/serializer.js`** (task H5, 2026-07-06 — first
+   engine-source change; marked `@handhold-patch H5` in the file):
+   - Extracted the inline blacklist/whitelist resolver in `getFlatTree` into an
+     exported `resolveElementList`, and extended it to FLATTEN function results
+     that are element collections (array/NodeList/any iterable), dropping
+     nullish results. Upstream mapped fn→value 1:1, which only supports
+     blacklisting exact elements (`domTree.js` matches `includes(element)`).
+   - Why: Handhold's `AgentMode` must hide the ENTIRE widget subtree
+     (`#handhold-container` and every descendant) from engine snapshots, so the
+     agent can never see or act on Handhold's own UI (e.g. click its own Allow
+     button). The entry is a function re-evaluated on every snapshot, so
+     dynamically rendered widget UI (confirm cards, activity lines) stays
+     excluded.
+   - Diff (semantic): `const resolve = (list=[]) => list.map(fn?fn():item)` →
+     `export const resolveElementList = (list=[]) => list.flatMap(...)` with
+     iterable-spread + nullish-drop; `getFlatTree` now uses it. No other engine
+     file touched; behavior for existing element/function-returning-element
+     entries is unchanged.
+   - Tests: `sdk/test/agent/resolve-blacklist.test.js` (Handhold addition, 3
+     tests). Security-neutral-or-better: the change only ever REMOVES elements
+     from the agent's view.
+
+6. **Added `sdk/src/agent/site/manifest.js`** (task H6.1, new module — intentional
+   forward-of-upstream addition): loadSiteManifest (THROWS unless
+   `reviewed === true`; refuses non-same-origin-absolute paths with an error
+   list), matchManifestPath (`:param` segments; unlisted → null),
+   listManifestPaths, describeCurrentPage. Tests:
+   `sdk/test/agent/site-manifest.test.js` (6).
+
+7. **Patched `sdk/src/agent/agent/tools.js`** (task H6.2, `@handhold-patch H6`):
+   added the `navigate` tool (`{path}` required string, shape-only validation —
+   manifest membership + sensitivity enforced by the controller/guard). The
+   vendored exact-tool-set pin in `sdk/test/agent/agent.test.js` failed on the
+   addition (by design) and was consciously updated to include `navigate`
+   (marker comment in the test); it remains an exact pin and still asserts no
+   `execute_javascript`/`evaluate`. Tests:
+   `sdk/test/agent/navigate-tool.test.js` (4).
+
+8. **Patched `sdk/src/agent/policy/PolicyGuard.js`** (task H6.3,
+   `@handhold-patch H6`): `check()` input gains optional `forceSensitive`
+   (string reason) — callers that KNOW an action is sensitive (manifest
+   `sensitive: true` pages) force the fail-closed confirm gate. Strictly
+   additive: it can only ADD the gate; keyword/attribute detection is unchanged.
+
+9. **Patched `sdk/src/agent/controller.js` + `sdk/src/agent/index.js`**
+   (task H6.3, `@handhold-patch H6`): GuardedController accepts `siteManifest`
+   (validated) + injectable `navigateImpl` (default `location.assign`);
+   `act('navigate')` runs before the snapshot requirement — no manifest →
+   unavailable; unlisted path → refused BEFORE the guard with the valid-path
+   list (no audit/rate cost); listed path → PolicyGuard.check (origin re-check,
+   rate limit, audit; sensitive forces confirm) → `navigateImpl(origin+path)`.
+   TrustedPageAgent accepts raw `siteManifest` JSON and validates it AT
+   CONSTRUCTION via loadSiteManifest (unreviewed → throw), passes `navigateImpl`
+   through, and hands the validated manifest to the loop. Tests:
+   `sdk/test/agent/navigate-guarded.test.js` (9; sensitive-gate teeth proven).
+
+10. **Patched `sdk/src/agent/agent/prompts.js` + `sdk/src/agent/agent/AgentLoop.js`**
+    (task H6.4, `@handhold-patch H6`): `buildSystemPrompt({manifest, task})`
+    renders a `<site_map>` section (trusted, human-reviewed — outside
+    `<untrusted_page_content>`) with SENSITIVE flags and reach trails, capped
+    ~2 kB with task-keyword priority; `buildStateMessage` gains an optional
+    `Current page:` line; AgentLoop accepts `siteManifest`, builds the system
+    prompt per run with the task, resolves Current page via describeCurrentPage.
+    Zero-arg `buildSystemPrompt()` unchanged. Tests:
+    `sdk/test/agent/prompts-sitemap.test.js` (5).
+
+11. **Patched `sdk/src/agent/agent/AgentLoop.js` + `sdk/src/agent/index.js`**
+    (task H7, `@handhold-patch H7`): checkpoint/resume support.
+    `AgentLoop.run(task, {restoredHistory, stepsUsed})` — restored entries are
+    prior CONTEXT, each prefixed `(restored)` (never double-prefixed) so the
+    model cannot read them as fresh instructions; the step budget CONTINUES
+    (first live step = stepsUsed + 1 of the same maxSteps). New
+    `getRunState()` → `{history, stepsUsed}` (loop) and TrustedPageAgent
+    proxy adding the guard's `audit` — read by the Handhold bridge immediately
+    before a navigation to write its checkpoint. Upstream activity/history
+    ordering deliberately untouched (the `executed` event still fires before
+    the history push; the bridge adds its own synthetic marker for the
+    in-flight navigation). Tests: `sdk/test/agent/resume-loop.test.js` (4;
+    prefix teeth proven).
+
+12. **Patched `sdk/src/agent/agent/AgentLoop.js`** (task H9, `@handhold-patch H9`):
+    consecutive-repeat guard. Live testing surfaced runs that completed the task
+    but never called `done`, then repeated the same action toward the step cap
+    ("continued endlessly"). The loop now tracks the `(actionName + JSON(input))`
+    signature: 3 identical repeats in a row inject a strong "call done or change
+    approach" nudge into history instead of executing; 5 stop the run with a
+    failure report. Any different action resets the counter, so legitimate
+    varied multi-step runs (and the 90 prior tests) are untouched. Reset per
+    run alongside history/step state. Tests:
+    `sdk/test/agent/repeat-guard.test.js` (3). (Complements Handhold-side task
+    framing in `AgentMode.buildTask` — done-criterion + ask-don't-invent — which
+    is not a vendor change.)
+
+12b. **Patched `sdk/src/agent/agent/AgentLoop.js` + `agent/prompts.js`** (round 6,
+    `@handhold-patch H9`): action-format loop fix. Live, llama-3.3-70b took the
+    prompt's `tool_name` placeholder literally and emitted a FLAT action
+    (`{"tool_name":"click_element_by_index","index":3}`) instead of
+    tool-name-as-key (`{"click_element_by_index":{...}}`); the strict single-key
+    parser threw every step → infinite parse-fail loop (the repeat guard misses
+    it because parse failures `continue` before it). Three parts:
+    (1) `parseAgentOutput` tolerates flat variants (`tool_name`/`tool`/`name`/
+    `action_name` + inline fields or `input`/`args`/`arguments`/`parameters`);
+    security unchanged (validateToolInput + PolicyGuard still gate).
+    (2) prompt output-contract shows a concrete `{"click_element_by_index":
+    {"index":0}}` example and says "the tool name IS the key; do not use a
+    tool_name field."
+    (3) consecutive parse-failures are bounded (5 → stop, ≥3 → nudge with an
+    example), so a stuck model can't burn all maxSteps. Tests:
+    `sdk/test/agent/parse-tolerant.test.js` (6) + a parse-fail-loop case in
+    `repeat-guard.test.js`.
+    (5) consecutive LLM-call failures are bounded (>=3 → stop): when the provider
+    is down/rate-limited (Groq daily-token 429 → proxy error) every call throws;
+    without this the loop "thinks" through all maxSteps. Test in
+    `repeat-guard.test.js`.
+    (4) ask_user is bounded by PROGRESS, not a fixed total (a form can have any
+    number of fields): consecutive asks with no intervening successful page
+    action are capped (>4 → stop); any successful click/type/select/nav resets
+    the counter, so ask-then-fill for a 9-field form completes. The answer also
+    feeds back "use this EXACT value; do not ask again". Live: a model asked for
+    a title, got it, then asked forever (repeat guard misses it when wording
+    varies). Tests: loop + any-size-form cases in `repeat-guard.test.js`.
+
+If a future task must patch engine source, add a numbered entry here with the
+file, the diff, and the reason.
+
+## Running the engine tests
+
+```bash
+cd sdk
+npm run test:agent   # node --test test/agent/*.test.js
+                     # → 94 pass (62 engine + 1 invariant + 3 blacklist-resolve
+                     #    + 24 whole-site + 4 checkpoint/resume)
+```
+
+`npm test` (jest) is configured to ignore `test/agent/` — the engine suite runs
+under `node --test`, not jest.

package/src/agent/agent/AgentLoop.js

@@ -0,0 +1,366 @@
+/**
+ * AgentLoop.js — the ReAct loop (observe → think → act).
+ * Structure adapted from alibaba/page-agent PageAgentCore (MIT), rewritten:
+ *  - every action goes through controller.act(), which enforces PolicyGuard;
+ *    the loop itself has NO direct DOM access and no way to bypass the guard
+ *  - LLM output is parsed as a JSON "macro action" (works with hosted models
+ *    and local models that lack native tool calling)
+ *  - unknown tools / invalid inputs never execute; the error is fed back to
+ *    the model as an observation instead
+ */
+import { buildStateMessage, buildSystemPrompt } from './prompts.js'
+import { validateToolInput } from './tools.js'
+// @handhold-patch H6 (VENDOR.md): Current-page resolution from the site manifest.
+import { describeCurrentPage } from '../site/manifest.js'
+
+/**
+ * Extract the agent's JSON macro action from raw model text.
+ * Tolerates markdown fences and preamble/postamble chatter (common with
+ * small local models). Throws with a clear message when no JSON is found.
+ */
+export function parseAgentOutput(text) {
+	let candidate = null
+
+	// Prefer fenced ```json blocks if present.
+	const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/)
+	if (fence) candidate = fence[1]
+
+	if (!candidate) {
+		// Find the first balanced top-level {...}
+		const start = text.indexOf('{')
+		if (start !== -1) {
+			let depth = 0
+			let inString = false
+			let escape = false
+			for (let i = start; i < text.length; i++) {
+				const ch = text[i]
+				if (escape) { escape = false; continue }
+				if (ch === '\\') { escape = true; continue }
+				if (ch === '"') inString = !inString
+				if (inString) continue
+				if (ch === '{') depth++
+				if (ch === '}') {
+					depth--
+					if (depth === 0) {
+						candidate = text.slice(start, i + 1)
+						break
+					}
+				}
+			}
+		}
+	}
+
+	if (!candidate) throw new Error('Model output contains no JSON object.')
+
+	let parsed
+	try {
+		parsed = JSON.parse(candidate)
+	} catch (e) {
+		throw new Error(`Model output JSON failed to parse: ${e.message}`)
+	}
+
+	const action = parsed.action
+	if (!action || typeof action !== 'object' || Array.isArray(action)) {
+		throw new Error('Model output is missing an "action" object.')
+	}
+
+	/**
+	 * @handhold-patch H9 (VENDOR.md) — tolerant action extraction.
+	 * Expected form is tool-name-as-key: { "click_element_by_index": {..} }.
+	 * But smaller models (llama-3.3-70b) took the prompt's `tool_name` placeholder
+	 * literally and emitted a FLAT object: { "tool_name": "click_...", "index": 3 },
+	 * which the strict single-key rule rejected -> infinite parse-fail loop.
+	 * Accept the common flat variants. Security is unchanged: validateToolInput
+	 * strips unknown fields and rejects unknown tools, and PolicyGuard still gates.
+	 */
+	const NAME_KEYS = ['tool_name', 'tool', 'name', 'action_name']
+	const INPUT_KEYS = ['input', 'args', 'arguments', 'parameters', 'params']
+	let actionName, actionInput
+	const nameKey = NAME_KEYS.find((k) => typeof action[k] === 'string')
+	if (nameKey) {
+		actionName = action[nameKey]
+		const inputKey = INPUT_KEYS.find((k) => action[k] && typeof action[k] === 'object' && !Array.isArray(action[k]))
+		if (inputKey) {
+			actionInput = action[inputKey]
+		} else {
+			actionInput = { ...action }
+			delete actionInput[nameKey]
+		}
+	} else {
+		const names = Object.keys(action)
+		if (names.length !== 1) {
+			throw new Error(`"action" must name exactly one tool (as the key, e.g. {"click_element_by_index":{...}}), got keys: ${names.join(', ')}.`)
+		}
+		actionName = names[0]
+		actionInput = action[names[0]] ?? {}
+	}
+	if (typeof actionInput !== 'object' || actionInput === null || Array.isArray(actionInput)) {
+		actionInput = {}
+	}
+
+	return {
+		evaluation: String(parsed.evaluation_previous_goal ?? ''),
+		memory: String(parsed.memory ?? ''),
+		nextGoal: String(parsed.next_goal ?? ''),
+		actionName: String(actionName),
+		actionInput,
+	}
+}
+
+export class AgentLoop {
+	#llm
+	#controller
+	#maxSteps
+	#onAskUser
+	#onActivity
+	#waitImpl
+	#siteManifest
+	#history = []
+	#stopped = false
+	#currentStep = 0
+	// @handhold-patch H9: consecutive-repeat guard (see VENDOR.md)
+	#lastSignature = null
+	#repeatCount = 0
+	#parseFailCount = 0
+	#asksSinceProgress = 0
+	#llmFailCount = 0
+
+	/**
+	 * @param {Object} cfg
+	 * @param {{complete: Function}} cfg.llm            from createLLM()
+	 * @param {{getBrowserState: Function, act: Function}} cfg.controller
+	 * @param {number} [cfg.maxSteps=25]
+	 * @param {(q:string)=>Promise<string>} [cfg.onAskUser]
+	 * @param {(ev:Object)=>void} [cfg.onActivity]      UI feedback hook
+	 * @param {(s:number)=>Promise<void>} [cfg.waitImpl] injectable for tests
+	 * @param {Object} [cfg.siteManifest]  @handhold-patch H6: validated manifest —
+	 *        feeds the <site_map> system section + Current-page state line
+	 */
+	constructor(cfg) {
+		this.#llm = cfg.llm
+		this.#controller = cfg.controller
+		this.#maxSteps = cfg.maxSteps ?? 25
+		this.#onAskUser = cfg.onAskUser ?? null
+		this.#onActivity = cfg.onActivity ?? (() => {})
+		this.#waitImpl = cfg.waitImpl ?? ((s) => new Promise((r) => setTimeout(r, s * 1000)))
+		this.#siteManifest = cfg.siteManifest ?? null
+	}
+
+	historyText() {
+		return this.#history.join('\n')
+	}
+
+	stop() {
+		this.#stopped = true
+	}
+
+	/**
+	 * @handhold-patch H7 (see sdk/src/agent/VENDOR.md) — checkpoint support.
+	 * Snapshot of the run for cross-page persistence: the bridge reads this
+	 * immediately before a navigation to write its checkpoint.
+	 */
+	getRunState() {
+		return { history: [...this.#history], stepsUsed: this.#currentStep }
+	}
+
+	/**
+	 * Run a task to completion.
+	 * @handhold-patch H7: `restoredHistory` + `stepsUsed` resume a checkpointed
+	 * run. Restored entries are PRIOR CONTEXT, never fresh instructions — each
+	 * is prefixed "(restored)" (no double prefixing) — and the step budget
+	 * CONTINUES: the first live step is stepsUsed + 1 of the same maxSteps.
+	 * @returns {Promise<{success: boolean, text: string, steps: number}>}
+	 */
+	async run(task, { signal, restoredHistory, stepsUsed } = {}) {
+		this.#history = []
+		this.#stopped = false
+		this.#currentStep = 0
+		this.#lastSignature = null
+		this.#repeatCount = 0
+		this.#parseFailCount = 0
+		this.#asksSinceProgress = 0
+		this.#llmFailCount = 0
+		let startStep = 1
+		if (Array.isArray(restoredHistory) && restoredHistory.length) {
+			this.#history = restoredHistory.map((h) => {
+				const entry = String(h)
+				return entry.startsWith('(restored)') ? entry : `(restored) ${entry}`
+			})
+			if (Number.isInteger(stepsUsed) && stepsUsed > 0) {
+				startStep = Math.min(stepsUsed + 1, this.#maxSteps)
+			}
+		}
+		const system = buildSystemPrompt({ manifest: this.#siteManifest, task })
+
+		for (let step = startStep; step <= this.#maxSteps; step++) {
+			this.#currentStep = step
+			if (this.#stopped || signal?.aborted) {
+				return { success: false, text: 'Stopped by user.', steps: step - 1 }
+			}
+
+			// ---- observe ----
+			const state = await this.#controller.getBrowserState()
+
+			// ---- think ----
+			this.#onActivity({ type: 'thinking', step })
+			const userMessage = buildStateMessage({
+				task,
+				stepNumber: step,
+				maxSteps: this.#maxSteps,
+				historyText: this.historyText(),
+				url: state.url,
+				elementsString: state.elementsString,
+				currentPage: this.#siteManifest ? describeCurrentPage(this.#siteManifest, state.url) : null,
+			})
+
+			let reply
+			try {
+				reply = await this.#llm.complete({
+					system,
+					messages: [{ role: 'user', content: userMessage }],
+					signal,
+				})
+				this.#llmFailCount = 0
+			} catch (e) {
+				if (signal?.aborted) return { success: false, text: 'Stopped by user.', steps: step }
+				// @handhold-patch H9 (VENDOR.md): bound consecutive LLM failures.
+				// When the assistant service is down or rate-limited (e.g. Groq
+				// daily-token 429 -> proxy error), every call fails; without this
+				// the loop "thinks" its way through all maxSteps. Stop after 3.
+				this.#llmFailCount += 1
+				if (this.#llmFailCount >= 3) {
+					const text = `Stopped: the assistant service is unavailable right now (${e.message}). Please try again later.`
+					this.#onActivity({ type: 'done', step, success: false })
+					return { success: false, text, steps: step }
+				}
+				this.#history.push(`<step_${step}> LLM call failed: ${e.message}`)
+				continue
+			}
+
+			let parsed
+			try {
+				parsed = parseAgentOutput(reply.text)
+				this.#parseFailCount = 0
+			} catch (e) {
+				// @handhold-patch H9 (VENDOR.md): bound parse-fail loops. Parse
+				// failures `continue` before the repeat guard, so a model stuck on
+				// a bad output shape would otherwise burn all maxSteps. Stop after
+				// 5 in a row; nudge harder (with a concrete example) from the 3rd.
+				this.#parseFailCount += 1
+				if (this.#parseFailCount >= 5) {
+					const text = `Stopped: the model produced unparseable output ${this.#parseFailCount} times in a row (${e.message}).`
+					this.#onActivity({ type: 'done', step, success: false })
+					return { success: false, text, steps: step }
+				}
+				const example =
+					this.#parseFailCount >= 3
+						? ' A VALID reply looks like {"evaluation_previous_goal":"...","memory":"...","next_goal":"...","action":{"click_element_by_index":{"index":0}}} — the tool name is the KEY inside "action"; do NOT use a "tool_name" field.'
+						: ''
+				this.#history.push(
+					`<step_${step}> Your previous reply could not be parsed (${e.message}). Reply with ONE valid JSON object only.${example}`
+				)
+				continue
+			}
+
+			// ---- act ----
+			const { actionName, actionInput, nextGoal, evaluation, memory } = parsed
+			const valid = validateToolInput(actionName, actionInput)
+			if (!valid.ok) {
+				this.#history.push(
+					`<step_${step}> Goal: ${nextGoal} | Action ${actionName} REJECTED: ${valid.error}`
+				)
+				continue
+			}
+			const input = valid.value
+
+			if (actionName === 'done') {
+				this.#onActivity({ type: 'executing', step, actionName, input, nextGoal })
+				this.#history.push(`<step_${step}> done: ${input.text}`)
+				this.#onActivity({ type: 'done', step, success: input.success })
+				return { success: input.success !== false, text: input.text, steps: step }
+			}
+
+			/**
+			 * @handhold-patch H9 (VENDOR.md) — consecutive-repeat guard.
+			 * Live testing surfaced runs that completed the task but never called
+			 * done, then repeated the same action toward the step cap. Track the
+			 * (action + input) signature: after 3 identical repeats in a row, feed
+			 * a strong nudge instead of executing; after 5, stop with a clear
+			 * failure so the loop can never run away. Progress (any different
+			 * action) resets the counter, so legitimate varied steps are untouched.
+			 */
+			const signature = `${actionName}:${JSON.stringify(input)}`
+			if (signature === this.#lastSignature) {
+				this.#repeatCount += 1
+			} else {
+				this.#lastSignature = signature
+				this.#repeatCount = 1
+			}
+			if (this.#repeatCount >= 5) {
+				const text = `Stopped: repeated the same action (${actionName}) ${this.#repeatCount} times with no progress. If the task looks complete it likely is; otherwise it is blocked.`
+				this.#onActivity({ type: 'done', step, success: false })
+				return { success: false, text, steps: step }
+			}
+			if (this.#repeatCount >= 3) {
+				this.#history.push(
+					`<step_${step}> You have chosen the SAME action ${this.#repeatCount} times in a row with no change. ` +
+						`If the objective is already achieved, call done(success=true) NOW. Otherwise try a DIFFERENT approach — do not repeat this action.`
+				)
+				continue
+			}
+
+			this.#onActivity({ type: 'executing', step, actionName, input, nextGoal })
+
+			let resultMessage
+			if (actionName === 'wait') {
+				await this.#waitImpl(input.seconds ?? 1)
+				resultMessage = `Waited ${input.seconds ?? 1}s.`
+			} else if (actionName === 'ask_user') {
+				// @handhold-patch H9 (VENDOR.md): bound ask_user WITHOUT a fixed
+				// total cap — a form can have any number of fields, so asking once
+				// per field (and filling it) must be unlimited. What's a loop is
+				// asking repeatedly WITHOUT making progress on the page. This
+				// counter resets on any successful page action (below); only
+				// consecutive asks with no intervening progress trip it.
+				this.#asksSinceProgress += 1
+				if (this.#asksSinceProgress > 4) {
+					const text = 'Stopped: I asked for input several times without being able to act on the answers. Please try again or do this step yourself.'
+					this.#onActivity({ type: 'done', step, success: false })
+					return { success: false, text, steps: step }
+				}
+				if (!this.#onAskUser) {
+					resultMessage = 'ask_user is unavailable (no handler configured). Proceed without it or call done.'
+				} else {
+					try {
+						const answer = await this.#onAskUser(input.question)
+						resultMessage = `User answered: "${answer}". Use this EXACT value in your next action (e.g. input_text). Do not ask for it again.`
+					} catch {
+						resultMessage = 'User did not answer.'
+					}
+				}
+			} else {
+				try {
+					const result = await this.#controller.act(actionName, input)
+					resultMessage = result.message
+					// Progress on the page (a successful click/type/select/nav)
+					// clears the ask-without-progress counter, so the next field's
+					// question is fine — forms of any size can be filled.
+					if (result.success) this.#asksSinceProgress = 0
+				} catch (e) {
+					resultMessage = `Action failed: ${e.message}`
+				}
+			}
+
+			this.#onActivity({ type: 'executed', step, actionName, resultMessage })
+			this.#history.push(
+				`<step_${step}> Eval: ${evaluation} | Memory: ${memory} | Goal: ${nextGoal} | ${actionName} → ${resultMessage}`
+			)
+		}
+
+		return {
+			success: false,
+			text: `Reached max steps (${this.#maxSteps}) without completing the task.`,
+			steps: this.#maxSteps,
+		}
+	}
+}