handhold-sdk 1.0.0

package/src/agent/dom/redact.js

@@ -0,0 +1,98 @@
+/**
+ * redact.js — PII redaction applied to page text/attributes BEFORE they are
+ * serialized into the LLM prompt.
+ *
+ * Upstream (alibaba/page-agent) left this as an open TODO in dom/index.ts
+ * ("@todo 数据脱敏过滤器" — data-masking filter) and their own
+ * terms-and-privacy.md admits HTML cleaning "does not guarantee removal of
+ * sensitive information". This module is the missing piece.
+ *
+ * Design notes:
+ * - Redaction is ON by default. Secure by default; opt out per category.
+ * - Card numbers are only redacted when Luhn-valid, so 16-digit order ids
+ *   and tracking numbers survive (a naive \d{16} rule destroys e-commerce
+ *   pages and makes the agent useless on them).
+ * - This is a best-effort net, not a guarantee. Do not point the agent at
+ *   pages containing data you are not allowed to send to your LLM provider.
+ */
+
+function luhnValid(digits) {
+	let sum = 0
+	let alt = false
+	for (let i = digits.length - 1; i >= 0; i--) {
+		let d = digits.charCodeAt(i) - 48
+		if (alt) {
+			d *= 2
+			if (d > 9) d -= 9
+		}
+		sum += d
+		alt = !alt
+	}
+	return sum % 10 === 0
+}
+
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g
+
+// Phones must show phone-ish intent: a leading +country code, parentheses,
+// or dash/dot separators. Plain space-separated digit groups (order numbers,
+// non-Luhn ids) are deliberately NOT treated as phones.
+const PHONE_RE = /(?:\+\d{1,3}(?:[ .-]?\d{2,4}){2,4}|(?:\(\d{2,4}\)[ .-]?)\d{3,4}[ .-]\d{3,4}|\d{3,4}[.-]\d{3,4}[.-]\d{3,4})/g
+
+// Last char must be a digit so trailing whitespace is never consumed.
+const CARD_CANDIDATE_RE = /\b\d(?:[ -]?\d){12,18}\b/g
+
+const SSN_RE = /\b\d{3}-\d{2}-\d{4}\b/g
+
+function countDigits(s) {
+	let n = 0
+	for (const ch of s) if (ch >= '0' && ch <= '9') n++
+	return n
+}
+
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.email=true]
+ * @param {boolean} [options.phone=true]
+ * @param {boolean} [options.card=true]
+ * @param {boolean} [options.ssn=true]
+ * @param {{pattern: RegExp, label: string}[]} [options.extraPatterns]
+ * @returns {(text: string) => string}
+ */
+export function createRedactor(options = {}) {
+	const { email = true, phone = true, card = true, ssn = true, extraPatterns = [] } = options
+
+	return function redact(text) {
+		if (typeof text !== 'string' || text.length === 0) return text
+		let out = text
+
+		if (email) out = out.replace(EMAIL_RE, '[EMAIL]')
+		if (ssn) out = out.replace(SSN_RE, '[SSN]')
+
+		if (card) {
+			out = out.replace(CARD_CANDIDATE_RE, (match) => {
+				const digits = match.replace(/[ -]/g, '')
+				if (digits.length >= 13 && digits.length <= 19 && luhnValid(digits)) return '[CARD]'
+				return match
+			})
+		}
+
+		if (phone) {
+			out = out.replace(PHONE_RE, (match) => {
+				// require enough digits to plausibly be a phone number,
+				// and at least one separator (so plain long numbers pass through
+				// to the card check instead)
+				if (countDigits(match) >= 9 && /[ .-]/.test(match)) return '[PHONE]'
+				return match
+			})
+		}
+
+		for (const { pattern, label } of extraPatterns) {
+			out = out.replace(pattern, label)
+		}
+
+		return out
+	}
+}
+
+/** Default redactor with everything on. */
+export const redactText = createRedactor()

package/src/agent/dom/serializer.js

@@ -0,0 +1,332 @@
+/**
+ * serializer.js — turns the domTree engine's flat tree into (1) the indexed
+ * text snapshot the LLM reads and (2) a selector map of index → live element.
+ *
+ * Ported from alibaba/page-agent packages/page-controller/src/dom/index.ts (MIT),
+ * with two deliberate changes:
+ *   1. REDACTION (new): every text fragment and attribute value passes through
+ *      a redactor before entering the snapshot. Upstream left this as an open
+ *      TODO ("@todo 数据脱敏过滤器"). Default redactor strips emails, phones,
+ *      Luhn-valid card numbers, SSNs. See dom/redact.js.
+ *   2. No import-time side effects: upstream registers window listeners at
+ *      module load; here installNavigationCleanup() must be called explicitly.
+ */
+
+import domTree from './domTree.js'
+import { redactText } from './redact.js'
+
+const DEFAULT_VIEWPORT_EXPANSION = -1
+
+const SEMANTIC_TAGS = new Set(['nav', 'menu', 'header', 'footer', 'aside', 'dialog'])
+
+const DEFAULT_INCLUDE_ATTRIBUTES = [
+	'title', 'type', 'checked', 'name', 'role', 'value', 'placeholder',
+	'data-date-format', 'alt', 'aria-label', 'aria-expanded', 'data-state',
+	'aria-checked',
+	'id', 'for',
+	'target',
+	'aria-haspopup', 'aria-controls', 'aria-owns',
+	'contenteditable',
+	// needed by PolicyGuard's credential/payment detection
+	'autocomplete',
+]
+
+const newElementsCache = new WeakMap()
+
+/**
+ * @handhold-patch H5 (see sdk/src/agent/VENDOR.md, patch #5)
+ * Resolve blacklist/whitelist entries. Upstream mapped fn->value 1:1, which
+ * only supports blacklisting exact elements. Handhold must hide its WHOLE
+ * widget subtree (#handhold-container and every descendant) from snapshots,
+ * so functions may now return element collections (array/NodeList/iterable):
+ * results are flattened and nullish results dropped. Entries are re-evaluated
+ * on every snapshot, catching dynamically rendered widget UI.
+ */
+export const resolveElementList = (list = []) =>
+	list.flatMap((item) => {
+		const v = typeof item === 'function' ? item() : item
+		if (v == null) return []
+		if (typeof v === 'object' && typeof v[Symbol.iterator] === 'function') return [...v]
+		return [v]
+	})
+
+export function getFlatTree(config = {}) {
+	const viewportExpansion = config.viewportExpansion ?? DEFAULT_VIEWPORT_EXPANSION
+
+	const resolve = resolveElementList
+
+	const elements = domTree({
+		doHighlightElements: config.highlight ?? false,
+		debugMode: false,
+		focusHighlightIndex: -1,
+		viewportExpansion,
+		interactiveBlacklist: resolve(config.interactiveBlacklist),
+		interactiveWhitelist: resolve(config.interactiveWhitelist),
+		highlightOpacity: config.highlightOpacity ?? 0.0,
+		highlightLabelOpacity: config.highlightLabelOpacity ?? 0.1,
+	})
+
+	const currentUrl = window.location.href
+	for (const nodeId in elements.map) {
+		const node = elements.map[nodeId]
+		if (node.isInteractive && node.ref) {
+			if (!newElementsCache.has(node.ref)) {
+				newElementsCache.set(node.ref, currentUrl)
+				node.isNew = true
+			}
+		}
+	}
+
+	return elements
+}
+
+const globRegexCache = new Map()
+function globToRegex(pattern) {
+	let regex = globRegexCache.get(pattern)
+	if (!regex) {
+		const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+		regex = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`)
+		globRegexCache.set(pattern, regex)
+	}
+	return regex
+}
+
+function matchAttributes(attrs, patterns) {
+	const result = {}
+	for (const pattern of patterns) {
+		if (pattern.includes('*')) {
+			const regex = globToRegex(pattern)
+			for (const key of Object.keys(attrs)) {
+				if (regex.test(key) && attrs[key].trim()) result[key] = attrs[key].trim()
+			}
+		} else {
+			const value = attrs[pattern]
+			if (value && value.trim()) result[pattern] = value.trim()
+		}
+	}
+	return result
+}
+
+/**
+ * @param {Object} flatTree  output of getFlatTree / domTree
+ * @param {Object} [options]
+ * @param {string[]} [options.includeAttributes]
+ * @param {boolean} [options.keepSemanticTags=false]
+ * @param {(s: string) => string} [options.redactor]  defaults to full redaction; pass (s)=>s to disable (NOT recommended)
+ * @returns {string}
+ */
+export function flatTreeToString(flatTree, options = {}) {
+	const {
+		includeAttributes = [],
+		keepSemanticTags = false,
+		redactor = redactText,
+	} = options
+
+	const includeAttrs = [...includeAttributes, ...DEFAULT_INCLUDE_ATTRIBUTES]
+
+	const capTextLength = (text, maxLength) =>
+		text.length > maxLength ? text.substring(0, maxLength) + '...' : text
+
+	const buildTreeNode = (nodeId) => {
+		const node = flatTree.map[nodeId]
+		if (!node) return null
+
+		if (node.type === 'TEXT_NODE') {
+			return {
+				type: 'text',
+				text: redactor(node.text ?? ''),
+				isVisible: node.isVisible,
+				parent: null,
+				children: [],
+			}
+		}
+
+		const children = []
+		if (node.children) {
+			for (const childId of node.children) {
+				const child = buildTreeNode(childId)
+				if (child) children.push(child)
+			}
+		}
+
+		const attributes = {}
+		for (const [k, v] of Object.entries(node.attributes ?? {})) {
+			attributes[k] = redactor(String(v))
+		}
+
+		return {
+			type: 'element',
+			tagName: node.tagName,
+			attributes,
+			isVisible: node.isVisible ?? false,
+			isInteractive: node.isInteractive ?? false,
+			isTopElement: node.isTopElement ?? false,
+			isNew: node.isNew ?? false,
+			highlightIndex: node.highlightIndex,
+			parent: null,
+			children,
+			extra: node.extra ?? {},
+		}
+	}
+
+	const setParentReferences = (node, parent = null) => {
+		node.parent = parent
+		for (const child of node.children) setParentReferences(child, node)
+	}
+
+	const rootNode = buildTreeNode(flatTree.rootId)
+	if (!rootNode) return ''
+	setParentReferences(rootNode)
+
+	const hasParentWithHighlightIndex = (node) => {
+		let current = node.parent
+		while (current) {
+			if (current.type === 'element' && current.highlightIndex !== undefined) return true
+			current = current.parent
+		}
+		return false
+	}
+
+	const processNode = (node, depth, result) => {
+		let nextDepth = depth
+		const depthStr = '\t'.repeat(depth)
+
+		if (node.type === 'element') {
+			const isSemantic = keepSemanticTags && node.tagName && SEMANTIC_TAGS.has(node.tagName)
+
+			if (node.highlightIndex !== undefined) {
+				nextDepth += 1
+
+				const text = getAllTextTillNextClickableElement(node)
+				let attributesHtmlStr = ''
+
+				if (includeAttrs.length > 0 && node.attributes) {
+					const attributesToInclude = matchAttributes(node.attributes, includeAttrs)
+
+					const keys = Object.keys(attributesToInclude)
+					if (keys.length > 1) {
+						const keysToRemove = new Set()
+						const seenValues = {}
+						for (const key of keys) {
+							const value = attributesToInclude[key]
+							if (value.length > 5) {
+								if (value in seenValues) keysToRemove.add(key)
+								else seenValues[value] = key
+							}
+						}
+						for (const key of keysToRemove) delete attributesToInclude[key]
+					}
+
+					if (attributesToInclude.role === node.tagName) delete attributesToInclude.role
+
+					for (const attr of ['aria-label', 'placeholder', 'title']) {
+						if (
+							attributesToInclude[attr] &&
+							attributesToInclude[attr].toLowerCase().trim() === text.toLowerCase().trim()
+						) {
+							delete attributesToInclude[attr]
+						}
+					}
+
+					if (Object.keys(attributesToInclude).length > 0) {
+						attributesHtmlStr = Object.entries(attributesToInclude)
+							.map(([key, value]) => `${key}=${capTextLength(value, 20)}`)
+							.join(' ')
+					}
+				}
+
+				const highlightIndicator = node.isNew ? `*[${node.highlightIndex}]` : `[${node.highlightIndex}]`
+				let line = `${depthStr}${highlightIndicator}<${node.tagName ?? ''}`
+				if (attributesHtmlStr) line += ` ${attributesHtmlStr}`
+
+				if (node.extra && node.extra.scrollable) {
+					let scrollDataText = ''
+					if (node.extra.scrollData?.left) scrollDataText += `left=${node.extra.scrollData.left}, `
+					if (node.extra.scrollData?.top) scrollDataText += `top=${node.extra.scrollData.top}, `
+					if (node.extra.scrollData?.right) scrollDataText += `right=${node.extra.scrollData.right}, `
+					if (node.extra.scrollData?.bottom) scrollDataText += `bottom=${node.extra.scrollData.bottom}`
+					line += ` data-scrollable="${scrollDataText}"`
+				}
+
+				if (text) {
+					const trimmedText = text.trim()
+					if (!attributesHtmlStr) line += ' '
+					line += `>${trimmedText}`
+				} else if (!attributesHtmlStr) {
+					line += ' '
+				}
+
+				line += ' />'
+				result.push(line)
+			}
+
+			const emitSemantic = isSemantic && node.highlightIndex === undefined
+			const mark = emitSemantic ? result.length : -1
+			if (emitSemantic) {
+				result.push(`${depthStr}<${node.tagName}>`)
+				nextDepth += 1
+			}
+
+			for (const child of node.children) processNode(child, nextDepth, result)
+
+			if (emitSemantic) {
+				if (result.length === mark + 1) result.pop()
+				else result.push(`${depthStr}</${node.tagName}>`)
+			}
+		} else if (node.type === 'text') {
+			if (hasParentWithHighlightIndex(node)) return
+			if (node.parent && node.parent.type === 'element' && node.parent.isVisible && node.parent.isTopElement) {
+				result.push(`${depthStr}${node.text ?? ''}`)
+			}
+		}
+	}
+
+	const result = []
+	processNode(rootNode, 0, result)
+	return result.join('\n')
+}
+
+export const getAllTextTillNextClickableElement = (node, maxDepth = -1) => {
+	const textParts = []
+	const collectText = (currentNode, currentDepth) => {
+		if (maxDepth !== -1 && currentDepth > maxDepth) return
+		if (currentNode.type === 'element' && currentNode !== node && currentNode.highlightIndex !== undefined) return
+		if (currentNode.type === 'text' && currentNode.text) {
+			textParts.push(currentNode.text)
+		} else if (currentNode.type === 'element') {
+			for (const child of currentNode.children) collectText(child, currentDepth + 1)
+		}
+	}
+	collectText(node, 0)
+	return textParts.join('\n').trim()
+}
+
+export function getSelectorMap(flatTree) {
+	const selectorMap = new Map()
+	for (const key of Object.keys(flatTree.map)) {
+		const node = flatTree.map[key]
+		if (node.isInteractive && typeof node.highlightIndex === 'number') {
+			selectorMap.set(node.highlightIndex, node)
+		}
+	}
+	return selectorMap
+}
+
+export function cleanUpHighlights() {
+	const cleanupFunctions = window._highlightCleanupFunctions || []
+	for (const cleanup of cleanupFunctions) {
+		if (typeof cleanup === 'function') cleanup()
+	}
+	window._highlightCleanupFunctions = []
+}
+
+/** Call once from the controller. No import-time listeners (unlike upstream). */
+export function installNavigationCleanup() {
+	window.addEventListener('popstate', cleanUpHighlights)
+	window.addEventListener('hashchange', cleanUpHighlights)
+	window.addEventListener('beforeunload', cleanUpHighlights)
+	const navigation = window.navigation
+	if (navigation && typeof navigation.addEventListener === 'function') {
+		navigation.addEventListener('navigate', cleanUpHighlights)
+	}
+}

package/src/agent/dom/utils.js

@@ -0,0 +1,99 @@
+/**
+ * utils.js — ported from alibaba/page-agent packages/page-controller/src/utils/index.ts (MIT).
+ * Changes vs upstream:
+ *   - Pointer/mask CustomEvents removed. Upstream dispatched `PageAgent::MovePointerTo`
+ *     etc. to drive a visual cursor overlay; here those are optional hooks the host
+ *     app can register (see setPointerHooks). No hook → no-op, no artificial wait.
+ */
+
+// ======= type guards =======
+// @note instanceof fails for elements inside iframes, hence nodeType/tagName checks.
+
+export function isHTMLElement(el) {
+	return !!el && el.nodeType === 1
+}
+
+export function isInputElement(el) {
+	return el?.nodeType === 1 && el.tagName === 'INPUT'
+}
+
+export function isTextAreaElement(el) {
+	return el?.nodeType === 1 && el.tagName === 'TEXTAREA'
+}
+
+export function isSelectElement(el) {
+	return el?.nodeType === 1 && el.tagName === 'SELECT'
+}
+
+export function isAnchorElement(el) {
+	return el?.nodeType === 1 && el.tagName === 'A'
+}
+
+// ======= iframe helpers =======
+
+/** Iframe offset for translating element coordinates to top-frame viewport. */
+export function getIframeOffset(element) {
+	const frame = element.ownerDocument.defaultView?.frameElement
+	if (!frame) return { x: 0, y: 0 }
+	const rect = frame.getBoundingClientRect()
+	return { x: rect.left, y: rect.top }
+}
+
+/**
+ * Get native value setter from the element's own prototype (iframe-safe).
+ * Required so React's value-tracking sees the change (React patches the
+ * instance property; the prototype setter bypasses the patch, then the
+ * dispatched 'input' event makes React re-read the value).
+ */
+export function getNativeValueSetter(element) {
+	return Object.getOwnPropertyDescriptor(Object.getPrototypeOf(element), 'value').set
+}
+
+// ======= general utils =======
+
+export async function waitFor(seconds, signal) {
+	if (signal?.aborted) throw signal.reason ?? new DOMException('Aborted', 'AbortError')
+	await new Promise((resolve, reject) => {
+		const t = setTimeout(done, seconds * 1000)
+		function done() {
+			signal?.removeEventListener('abort', onAbort)
+			resolve()
+		}
+		function onAbort() {
+			clearTimeout(t)
+			reject(signal.reason ?? new DOMException('Aborted', 'AbortError'))
+		}
+		signal?.addEventListener('abort', onAbort, { once: true })
+	})
+}
+
+// ======= optional pointer-visual hooks (replaces upstream mask CustomEvents) =======
+
+let pointerHooks = null
+
+/**
+ * Register visual hooks: { movePointerTo(x,y), clickPointer(), enablePassThrough(), disablePassThrough() }
+ * All optional. Used purely for UX (showing a fake cursor); never load-bearing.
+ */
+export function setPointerHooks(hooks) {
+	pointerHooks = hooks
+}
+
+export async function movePointerToElement(element, x, y) {
+	if (!pointerHooks?.movePointerTo) return
+	const offset = getIframeOffset(element)
+	pointerHooks.movePointerTo(x + offset.x, y + offset.y)
+	await waitFor(0.3)
+}
+
+export async function clickPointer() {
+	pointerHooks?.clickPointer?.()
+}
+
+export async function enablePassThrough() {
+	pointerHooks?.enablePassThrough?.()
+}
+
+export async function disablePassThrough() {
+	pointerHooks?.disablePassThrough?.()
+}

package/src/agent/index.js

@@ -0,0 +1,169 @@
+/**
+ * trusted-page-agent — a security-first rebuild of alibaba/page-agent.
+ *
+ * Kept from upstream (MIT, audited): the browser-use DOM extraction engine
+ * (complex layouts, occlusion hit-testing, iframes, shadow DOM, scrollable
+ * regions), the serialization format, and the React-aware action dispatch.
+ *
+ * Replaced/added: no eval tool of any kind, mandatory origin allowlist,
+ * fail-closed human confirmation for sensitive actions, PII redaction before
+ * page text reaches the LLM, audit log, rate limit, prompt-injection
+ * hardening, and an LLM connector that takes either a hosted API key or a
+ * local model URL (Ollama / LM Studio / vLLM / any OpenAI-compatible server).
+ *
+ * @example Hosted (Anthropic):
+ *   const agent = new TrustedPageAgent({
+ *     llm: { provider: 'anthropic', apiKey: '...', model: 'claude-sonnet-4-6' },
+ *     allowedOrigins: [location.origin],
+ *     onConfirm: async (p) => confirm(`Allow: ${p.reason}?`),
+ *   })
+ *   const result = await agent.run('Fill the signup form with test data')
+ *
+ * @example Local (Ollama):
+ *   const agent = new TrustedPageAgent({
+ *     llm: { provider: 'openai-compatible', baseURL: 'http://localhost:11434/v1', model: 'qwen3:14b' },
+ *     allowedOrigins: [location.origin],
+ *     onConfirm: async (p) => confirm(`Allow: ${p.reason}?`),
+ *   })
+ */
+import { AgentLoop } from './agent/AgentLoop.js'
+import { GuardedController } from './controller.js'
+import { createLLM } from './llm/connector.js'
+import { PolicyGuard } from './policy/PolicyGuard.js'
+// @handhold-patch H6 (VENDOR.md): whole-site support (reviewed manifest + navigate).
+import { loadSiteManifest } from './site/manifest.js'
+
+export { AgentLoop, parseAgentOutput } from './agent/AgentLoop.js'
+export { TOOLS, validateToolInput } from './agent/tools.js'
+export { GuardedController, domSnapshotProvider } from './controller.js'
+export { createRedactor, redactText } from './dom/redact.js'
+export { flatTreeToString, getFlatTree, getSelectorMap } from './dom/serializer.js'
+export { setPointerHooks } from './dom/utils.js'
+export { createLLM } from './llm/connector.js'
+export { PolicyGuard } from './policy/PolicyGuard.js'
+export { ChatWidget } from './ui/ChatWidget.js'
+
+export class TrustedPageAgent {
+	#loop
+	#controller
+
+	/**
+	 * @param {Object} cfg
+	 * @param {Object} cfg.llm              createLLM() config: {provider, baseURL?, apiKey?, model, ...}
+	 * @param {string[]} cfg.allowedOrigins REQUIRED — origins the agent may act on
+	 * @param {(pending:{name,input,reason}) => Promise<boolean>} [cfg.onConfirm]
+	 *        Human gate for sensitive actions. Without it, sensitive actions are blocked.
+	 * @param {(question:string) => Promise<string>} [cfg.onAskUser]
+	 * @param {(ev:Object) => void} [cfg.onActivity]  UI feedback (thinking/executing/executed/done)
+	 * @param {number} [cfg.maxSteps=25]
+	 * @param {number} [cfg.maxActionsPerMinute=30]
+	 * @param {string[]} [cfg.extraSensitiveKeywords]
+	 * @param {Object} [cfg.domConfig]      engine options: viewportExpansion, interactiveBlacklist,
+	 *                                      includeAttributes, redactor, keepSemanticTags...
+	 * @param {Object} [cfg.siteManifest]   @handhold-patch H6: RAW manifest JSON as served by
+	 *                                      GET /api/v1/manifest. Validated here — construction
+	 *                                      THROWS unless reviewed === true (client-side gate).
+	 *                                      Without it the agent stays single-page.
+	 * @param {(url:string)=>void|Promise<void>} [cfg.navigateImpl]  injectable navigation
+	 */
+	constructor(cfg = {}) {
+		if (!cfg.llm) throw new Error('TrustedPageAgent: cfg.llm is required (see createLLM).')
+
+		const guard = new PolicyGuard({
+			allowedOrigins: cfg.allowedOrigins,
+			onConfirm: cfg.onConfirm,
+			extraSensitiveKeywords: cfg.extraSensitiveKeywords,
+			maxActionsPerMinute: cfg.maxActionsPerMinute,
+		})
+
+		// @handhold-patch H6: validate the manifest at the trust boundary. An
+		// unreviewed or malformed manifest must never configure the agent.
+		const siteManifest = cfg.siteManifest ? loadSiteManifest(cfg.siteManifest) : null
+
+		this.#controller = new GuardedController({
+			guard,
+			domConfig: cfg.domConfig,
+			siteManifest,
+			navigateImpl: cfg.navigateImpl,
+		})
+
+		this.#loop = new AgentLoop({
+			llm: createLLM(cfg.llm),
+			controller: this.#controller,
+			maxSteps: cfg.maxSteps,
+			onAskUser: cfg.onAskUser,
+			onActivity: cfg.onActivity,
+			siteManifest,
+		})
+	}
+
+	/** Run a natural-language task. Resolves with {success, text, steps}. */
+	run(task, opts) {
+		return this.#loop.run(task, opts)
+	}
+
+	/** Cooperative stop; the current step finishes, no further actions run. */
+	stop() {
+		this.#loop.stop()
+	}
+
+	/** Timestamped record of every action considered/allowed/blocked. */
+	getAuditLog() {
+		return this.#controller.getAuditLog()
+	}
+
+	/**
+	 * @handhold-patch H7 (VENDOR.md): run snapshot for cross-page checkpoints —
+	 * {history, stepsUsed} from the loop plus the guard's audit log.
+	 */
+	getRunState() {
+		return { ...this.#loop.getRunState(), audit: this.#controller.getAuditLog() }
+	}
+}
+
+/**
+ * One-liner: mount the chat-bubble UI and wire it to an agent.
+ * The widget becomes the human gate (Allow/Deny buttons), the ask_user
+ * channel, and the activity feed. Any onConfirm/onAskUser/onActivity you
+ * pass in agentConfig still wins over the widget defaults.
+ *
+ * @example
+ *   attachChatWidget({
+ *     llm: { provider: 'deepseek', apiKey: 'sk-...', model: 'deepseek-chat' },
+ *     allowedOrigins: [location.origin],
+ *   })
+ *
+ * @returns {{ agent: TrustedPageAgent, widget: ChatWidget }}
+ */
+export function attachChatWidget(agentConfig, widgetOptions = {}) {
+	let agent = null
+	const widget = new ChatWidgetClass({
+		...widgetOptions,
+		onTask: async (task) => {
+			widget.setBusy(true)
+			try {
+				const result = await agent.run(task)
+				widget.addMessage('agent', `${result.success ? '✅' : '⚠️'} ${result.text}`)
+			} catch (e) {
+				widget.addMessage('agent', `⚠️ Error: ${e.message}`)
+			} finally {
+				widget.setBusy(false)
+			}
+		},
+	})
+	widget.mount()
+
+	agent = new TrustedPageAgent({
+		onConfirm: (p) => widget.requestConfirm(p),
+		onAskUser: (q) => widget.askUser(q),
+		onActivity: (ev) => widget.showActivity(ev),
+		...agentConfig,
+	})
+
+	return { agent, widget }
+}
+
+// internal alias so attachChatWidget can construct without a circular re-import
+import { ChatWidget as ChatWidgetClass } from './ui/ChatWidget.js'
+
+export default TrustedPageAgent