handhold-sdk 1.0.0

package/src/agent/llm/connector.js

@@ -0,0 +1,143 @@
+/**
+ * connector.js — BYOK LLM client with two drivers:
+ *
+ *  1. 'openai-compatible' — one driver covers:
+ *       • OpenAI            baseURL: https://api.openai.com/v1        (apiKey required)
+ *       • OpenRouter        baseURL: https://openrouter.ai/api/v1     (apiKey required)
+ *       • Ollama (local)    baseURL: http://localhost:11434/v1        (no key)
+ *       • LM Studio (local) baseURL: http://localhost:1234/v1         (no key)
+ *       • vLLM (local/LAN)  baseURL: http://<host>:8000/v1            (key optional)
+ *  2. 'anthropic' — Claude via api.anthropic.com/v1/messages.
+ *
+ * Security properties:
+ *  - Keys live only in the object you construct; nothing here persists or
+ *    forwards them anywhere except the endpoint you configured.
+ *  - Plain-http endpoints are REJECTED unless the host is localhost/127.x/
+ *    ::1/private-LAN (10.x, 172.16-31.x, 192.168.x). Sending page content or
+ *    an API key over plaintext to a public host is a config mistake this
+ *    module refuses to make.
+ *  - No streaming, no retries-with-backdoor, no telemetry. One POST per call.
+ */
+
+const PRIVATE_HOST_RE = /^(localhost|127\.\d+\.\d+\.\d+|\[?::1\]?|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+)$/i
+
+function assertSafeBaseURL(baseURL) {
+	let u
+	try {
+		u = new URL(baseURL)
+	} catch {
+		throw new Error(`connector: invalid baseURL "${baseURL}"`)
+	}
+	if (u.protocol === 'https:') return
+	if (u.protocol === 'http:' && PRIVATE_HOST_RE.test(u.hostname)) return
+	throw new Error(
+		`connector: refusing plain-http baseURL "${baseURL}" for a non-local host. ` +
+		'Use https, or a localhost/private-LAN address for locally hosted models.'
+	)
+}
+
+/**
+ * @param {Object} config
+ * @param {'openai-compatible'|'anthropic'} config.provider
+ * @param {string} [config.baseURL]   required for openai-compatible
+ * @param {string} [config.apiKey]    optional for local endpoints
+ * @param {string} config.model
+ * @param {number} [config.temperature=0]
+ * @param {number} [config.maxTokens=2000]
+ * @param {typeof fetch} [config.fetchImpl]  injectable for tests
+ * @returns {{ complete: (args: {system: string, messages: {role:string,content:string}[], signal?: AbortSignal}) => Promise<{text: string, raw: any}> }}
+ */
+/**
+ * Named presets that normalize to the openai-compatible driver.
+ * keyRequired presets throw early rather than failing with a confusing 401.
+ */
+const PRESETS = {
+	deepseek: { baseURL: 'https://api.deepseek.com/v1', keyRequired: true },
+}
+
+export function createLLM(config) {
+	// Resolve presets (e.g. provider:'deepseek') to the generic driver.
+	if (config.provider in PRESETS) {
+		const preset = PRESETS[config.provider]
+		if (preset.keyRequired && !config.apiKey) {
+			throw new Error(`connector: apiKey is required for the ${config.provider} provider`)
+		}
+		config = { ...config, provider: 'openai-compatible', baseURL: config.baseURL ?? preset.baseURL }
+	}
+
+	const {
+		provider, apiKey, model,
+		temperature = 0, maxTokens = 2000,
+		fetchImpl = globalThis.fetch,
+	} = config
+
+	if (!model) throw new Error('connector: model is required')
+
+	if (provider === 'openai-compatible') {
+		if (!config.baseURL) throw new Error('connector: baseURL is required for openai-compatible provider')
+		assertSafeBaseURL(config.baseURL)
+		const baseURL = config.baseURL.replace(/\/+$/, '')
+
+		return {
+			async complete({ system, messages, signal }) {
+				const headers = { 'Content-Type': 'application/json' }
+				if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
+
+				const res = await fetchImpl(`${baseURL}/chat/completions`, {
+					method: 'POST',
+					headers,
+					signal,
+					body: JSON.stringify({
+						model,
+						temperature,
+						max_tokens: maxTokens,
+						messages: [{ role: 'system', content: system }, ...messages],
+					}),
+				})
+				if (!res.ok) {
+					const body = await res.text().catch(() => '')
+					throw new Error(`LLM request failed: HTTP ${res.status} ${body.slice(0, 300)}`)
+				}
+				const data = await res.json()
+				const text = data?.choices?.[0]?.message?.content ?? ''
+				return { text, raw: data }
+			},
+		}
+	}
+
+	if (provider === 'anthropic') {
+		if (!apiKey) throw new Error('connector: apiKey is required for the anthropic provider')
+
+		return {
+			async complete({ system, messages, signal }) {
+				const res = await fetchImpl('https://api.anthropic.com/v1/messages', {
+					method: 'POST',
+					signal,
+					headers: {
+						'Content-Type': 'application/json',
+						'x-api-key': apiKey,
+						'anthropic-version': '2023-06-01',
+						// allows calling from a browser page (official CORS opt-in header)
+						'anthropic-dangerous-direct-browser-access': 'true',
+					},
+					body: JSON.stringify({
+						model,
+						max_tokens: maxTokens,
+						temperature,
+						system,
+						messages,
+					}),
+				})
+				if (!res.ok) {
+					const body = await res.text().catch(() => '')
+					throw new Error(`LLM request failed: HTTP ${res.status} ${body.slice(0, 300)}`)
+				}
+				const data = await res.json()
+				const text = (data?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join('\n')
+				return { text, raw: data }
+			},
+		}
+	}
+
+	throw new Error(`connector: unknown provider "${provider}"`)
+}

package/src/agent/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/src/agent/policy/PolicyGuard.js

@@ -0,0 +1,172 @@
+/**
+ * PolicyGuard.js — the enforcement layer upstream doesn't have.
+ *
+ * Every action the LLM proposes goes through guard.check() BEFORE it touches
+ * the DOM. The guard is deliberately independent of the agent loop so a bug
+ * (or a prompt-injected detour) in the loop cannot bypass it.
+ *
+ * Guarantees:
+ *  1. Origin pinning  — actions run only if the current window origin is on
+ *     an explicit allowlist. Constructor THROWS if the list is missing/empty:
+ *     there is no "allow everywhere" default to forget about.
+ *  2. Fails closed    — sensitive actions (payments, deletion, submission,
+ *     credentials...) are BLOCKED unless a human onConfirm() callback
+ *     explicitly returns true. No handler => no sensitive actions, period.
+ *  3. Rate limiting   — hard ceiling on actions/minute, independent of the
+ *     LLM loop's own maxSteps.
+ *  4. Audit log       — timestamped record of every decision (allowed,
+ *     blocked, sensitive, reason) for post-hoc review.
+ */
+
+const DEFAULT_SENSITIVE_KEYWORDS = [
+	// destructive
+	'delete', 'remove', 'destroy', 'terminate', 'deactivate', 'revoke', 'cancel',
+	// financial
+	'pay', 'payment', 'purchase', 'buy', 'checkout', 'transfer', 'withdraw',
+	'send money', 'disbursement', 'payout', 'refund',
+	// commitment
+	'submit', 'confirm', 'approve', 'sign', 'agree', 'accept terms', 'place order',
+	// account/session
+	'logout', 'log out', 'sign out', 'unsubscribe', 'close account',
+	// comms
+	'send', 'publish', 'post', 'share',
+]
+
+const SENSITIVE_INPUT_TYPES = new Set(['password'])
+const SENSITIVE_INPUT_AUTOCOMPLETE = ['cc-number', 'cc-csc', 'cc-exp', 'current-password', 'new-password', 'one-time-code']
+
+export class PolicyGuard {
+	#allowedOrigins
+	#getOrigin
+	#onConfirm
+	#keywords
+	#maxPerMinute
+	#actionTimestamps = []
+	#auditLog = []
+
+	/**
+	 * @param {Object} config
+	 * @param {string[]} config.allowedOrigins        REQUIRED, non-empty. e.g. ['https://app.example.com']
+	 * @param {() => string} [config.getOrigin]       defaults to window.location.origin
+	 * @param {(pending: {name:string,input:Object,reason:string}) => Promise<boolean>} [config.onConfirm]
+	 * @param {string[]} [config.extraSensitiveKeywords]
+	 * @param {number} [config.maxActionsPerMinute=30]
+	 */
+	constructor(config = {}) {
+		if (!Array.isArray(config.allowedOrigins) || config.allowedOrigins.length === 0) {
+			throw new Error(
+				'PolicyGuard: allowedOrigins is required and must be a non-empty array. ' +
+				'There is intentionally no default — decide where this agent may act.'
+			)
+		}
+		this.#allowedOrigins = config.allowedOrigins.map((o) => o.replace(/\/+$/, ''))
+		this.#getOrigin = config.getOrigin ?? (() => globalThis.window?.location?.origin ?? 'unknown://')
+		this.#onConfirm = config.onConfirm ?? null
+		this.#keywords = [
+			...DEFAULT_SENSITIVE_KEYWORDS,
+			...(config.extraSensitiveKeywords ?? []).map((k) => k.toLowerCase()),
+		]
+		this.#maxPerMinute = config.maxActionsPerMinute ?? 30
+	}
+
+	/**
+	 * @param {Object} action
+	 * @param {string} action.name                          e.g. 'click', 'input_text'
+	 * @param {Object} action.input                         tool input from the LLM
+	 * @param {string} [action.elementText]                 visible text of the target element
+	 * @param {Record<string,string>} [action.elementAttributes]
+	 * @returns {Promise<{allowed: boolean, sensitive: boolean, reason: string}>}
+	 */
+	async check(action) {
+		const verdict = await this.#evaluate(action)
+		this.#auditLog.push({
+			ts: Date.now(),
+			name: action.name,
+			input: action.input,
+			elementText: action.elementText ?? '',
+			allowed: verdict.allowed,
+			sensitive: verdict.sensitive,
+			reason: verdict.reason,
+		})
+		return verdict
+	}
+
+	async #evaluate(action) {
+		// 1. origin pin
+		const origin = this.#getOrigin().replace(/\/+$/, '')
+		if (!this.#allowedOrigins.includes(origin)) {
+			return { allowed: false, sensitive: false, reason: `Origin ${origin} is not on the allowlist.` }
+		}
+
+		// 2. rate limit
+		const now = Date.now()
+		this.#actionTimestamps = this.#actionTimestamps.filter((t) => now - t < 60_000)
+		if (this.#actionTimestamps.length >= this.#maxPerMinute) {
+			return { allowed: false, sensitive: false, reason: `Rate limit: more than ${this.#maxPerMinute} actions/minute.` }
+		}
+		this.#actionTimestamps.push(now)
+
+		// 3. sensitivity gate (fails closed)
+		const sensitiveReason = this.#sensitiveReason(action)
+		if (sensitiveReason) {
+			if (!this.#onConfirm) {
+				return {
+					allowed: false, sensitive: true,
+					reason: `${sensitiveReason} — blocked: no onConfirm handler configured (fails closed).`,
+				}
+			}
+			let ok = false
+			try {
+				ok = (await this.#onConfirm({ name: action.name, input: action.input, reason: sensitiveReason })) === true
+			} catch {
+				ok = false
+			}
+			return ok
+				? { allowed: true, sensitive: true, reason: `${sensitiveReason} — approved by human.` }
+				: { allowed: false, sensitive: true, reason: `${sensitiveReason} — denied by human.` }
+		}
+
+		return { allowed: true, sensitive: false, reason: 'ok' }
+	}
+
+	#sensitiveReason(action) {
+		/**
+		 * @handhold-patch H6 (see sdk/src/agent/VENDOR.md) — forced sensitivity.
+		 * Callers that KNOW an action is sensitive (e.g. navigation to a page
+		 * the human-reviewed manifest marks sensitive:true) pass forceSensitive
+		 * with the reason. This can only ADD the confirm gate, never remove it:
+		 * keyword/attribute detection below still runs for everything else.
+		 */
+		if (typeof action.forceSensitive === 'string' && action.forceSensitive) {
+			return action.forceSensitive
+		}
+
+		const attrs = action.elementAttributes ?? {}
+		const type = (attrs.type ?? '').toLowerCase()
+		const autocomplete = (attrs.autocomplete ?? '').toLowerCase()
+
+		if (SENSITIVE_INPUT_TYPES.has(type)) return `Target is a ${type} field`
+		if (SENSITIVE_INPUT_AUTOCOMPLETE.some((v) => autocomplete.includes(v))) {
+			return `Target autocomplete="${autocomplete}" indicates credentials/payment data`
+		}
+
+		const haystack = [
+			action.elementText ?? '',
+			attrs['aria-label'] ?? '',
+			attrs.name ?? '',
+			attrs.value ?? '',
+			attrs.title ?? '',
+		].join(' ').toLowerCase()
+
+		for (const kw of this.#keywords) {
+			// word-boundary match so 'send' doesn't fire on 'ascending'
+			const re = new RegExp(`(^|[^a-z])${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z]|$)`)
+			if (re.test(haystack)) return `Action targets "${(action.elementText ?? '').slice(0, 60)}" (matched sensitive keyword "${kw}")`
+		}
+		return null
+	}
+
+	getAuditLog() {
+		return this.#auditLog.slice()
+	}
+}

package/src/agent/site/manifest.js

@@ -0,0 +1,145 @@
+/**
+ * site/manifest.js — Handhold whole-site addition (H6.1; VENDOR.md patch log).
+ *
+ * The site manifest is the HUMAN-REVIEWED map of pages the agent may know and
+ * navigate (specs/whole-site-control-design.md §5). This module is the
+ * client-side half of that contract:
+ *
+ *  - `reviewed: true` is REQUIRED to load. The backend already refuses to
+ *    serve unreviewed manifests (GET /api/v1/manifest -> 404); enforcing it
+ *    here again means even a tampered/bypassed transport cannot hand the
+ *    agent an unapproved map (defense in depth).
+ *  - Page paths are same-origin absolute: leading '/', no '//', no
+ *    scheme/host, no '..', no whitespace. `:param` segments are allowed
+ *    (/employees/:id). A manifest with any bad path is refused whole, with
+ *    every offending path in the error.
+ *  - Pages/states not listed DO NOT EXIST for the agent: matchManifestPath
+ *    returns null and the navigate tool refuses before the guard.
+ *
+ * Trust note: the manifest is trusted config (human-reviewed), unlike page
+ * content — it may appear in the system prompt outside untrusted tags.
+ */
+
+function pathError(path) {
+	if (typeof path !== 'string' || path.length === 0) return 'path must be a non-empty string'
+	if (!path.startsWith('/')) return `path must start with '/' (got "${path}")`
+	if (path.startsWith('//')) return `path must not be protocol-relative (got "${path}")`
+	if (path.includes('://')) return `path must not contain a scheme or host (got "${path}")`
+	if (path.includes('..')) return `path must not contain '..' (got "${path}")`
+	if (/\s/.test(path)) return `path must not contain whitespace (got "${path}")`
+	return null
+}
+
+/**
+ * Validate and normalize a raw manifest JSON (as served by the Handhold
+ * backend). Throws on anything that must never reach the agent.
+ * @returns {{version:number, origin:string, pages:Array}} normalized manifest
+ */
+export function loadSiteManifest(raw) {
+	if (!raw || typeof raw !== 'object') {
+		throw new Error('site manifest: expected an object')
+	}
+	if (raw.reviewed !== true) {
+		throw new Error(
+			'site manifest: refused — "reviewed" must be exactly true. ' +
+			'A human must review the site map before the agent may use it.'
+		)
+	}
+	const pages = Array.isArray(raw.pages) ? raw.pages : []
+	const errors = []
+	const normalized = pages.map((page, i) => {
+		const err = pathError(page?.path)
+		if (err) {
+			errors.push(`pages[${i}]: ${err}`)
+			return null
+		}
+		return {
+			path: page.path,
+			name: String(page.name ?? page.path),
+			purpose: page.purpose != null ? String(page.purpose) : '',
+			sensitive: page.sensitive === true,
+			states: Array.isArray(page.states)
+				? page.states.map((s) => ({
+						name: String(s?.name ?? ''),
+						steps: Array.isArray(s?.steps)
+							? s.steps.map((st) => ({
+									type: String(st?.type ?? ''),
+									role: st?.role != null ? String(st.role) : '',
+									name: st?.name != null ? String(st.name) : '',
+								}))
+							: [],
+					}))
+				: [],
+		}
+	})
+	if (errors.length) {
+		throw new Error(`site manifest: refused — invalid page paths:\n${errors.join('\n')}`)
+	}
+	return {
+		version: Number(raw.version ?? 1),
+		origin: String(raw.origin ?? ''),
+		pages: normalized,
+	}
+}
+
+/** Strip query/hash and a trailing slash (except root) from a concrete path. */
+function normalizeConcretePath(path) {
+	let p = String(path).split('?')[0].split('#')[0]
+	if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1)
+	return p
+}
+
+/**
+ * Resolve a concrete path against the manifest. Supports `:param` pattern
+ * segments (each matches exactly one non-empty segment). Returns the page or
+ * null — null means the page DOES NOT EXIST for the agent.
+ */
+export function matchManifestPath(manifest, path) {
+	if (!manifest || !Array.isArray(manifest.pages)) return null
+	const target = normalizeConcretePath(path)
+	if (pathError(target)) return null
+	const targetSegs = target.split('/').filter(Boolean)
+
+	for (const page of manifest.pages) {
+		const patternSegs = page.path.split('/').filter(Boolean)
+		if (patternSegs.length !== targetSegs.length) {
+			// exact-root special case: '/' matches '/'
+			if (page.path === '/' && target === '/') return page
+			continue
+		}
+		let ok = true
+		for (let i = 0; i < patternSegs.length; i++) {
+			const pat = patternSegs[i]
+			if (pat.startsWith(':')) {
+				if (!targetSegs[i]) { ok = false; break }
+			} else if (pat !== targetSegs[i]) {
+				ok = false
+				break
+			}
+		}
+		if (ok) return page
+	}
+	return null
+}
+
+/** Every page path — used in navigate-rejection errors for self-correction. */
+export function listManifestPaths(manifest) {
+	if (!manifest || !Array.isArray(manifest.pages)) return []
+	return manifest.pages.map((p) => p.path)
+}
+
+/**
+ * Resolve a full URL to a human label "name (path)" for the state message's
+ * `Current page:` line. Null when the URL is not a manifest page (caller
+ * falls back to the raw URL).
+ */
+export function describeCurrentPage(manifest, url) {
+	let pathname
+	try {
+		pathname = new URL(url).pathname
+	} catch {
+		return null
+	}
+	const page = matchManifestPath(manifest, pathname)
+	return page ? `${page.name} (${page.path})` : null
+}

package/src/agent/ui/ChatWidget.js

@@ -0,0 +1,219 @@
+/**
+ * ChatWidget.js — the "chatbot bubble" UI: a floating button bottom-right
+ * that opens a chat panel. Zero dependencies, injects its own styles once.
+ *
+ * Security notes (this is UI, but it sits in the trust path):
+ *  - All content is rendered with textContent, NEVER innerHTML — model output
+ *    and page-derived strings cannot inject markup into the host page.
+ *  - requestConfirm() renders the PolicyGuard reason with explicit
+ *    Allow/Deny buttons, so the human gate is a real UI affordance instead
+ *    of a window.confirm() that people click through.
+ *
+ * Wire-up (see TrustedPageAgent.attachWidget for the one-liner):
+ *   const widget = new ChatWidget({ title: 'Assistant', onTask: run })
+ *   widget.mount()
+ *   agent config: onConfirm: (p) => widget.requestConfirm(p),
+ *                 onAskUser: (q) => widget.askUser(q),
+ *                 onActivity: (ev) => widget.showActivity(ev)
+ */
+
+const STYLE = `
+.tpa-bubble{position:fixed;right:20px;bottom:20px;width:56px;height:56px;border-radius:50%;
+	border:0;background:#1a73e8;color:#fff;font-size:24px;cursor:pointer;z-index:2147483000;
+	box-shadow:0 4px 14px rgba(0,0,0,.25);transition:transform .15s}
+.tpa-bubble:hover{transform:scale(1.06)}
+.tpa-panel{position:fixed;right:20px;bottom:88px;width:340px;max-width:calc(100vw - 40px);
+	height:460px;max-height:calc(100vh - 120px);display:none;flex-direction:column;
+	background:#fff;border-radius:14px;box-shadow:0 8px 30px rgba(0,0,0,.3);z-index:2147483000;
+	font-family:system-ui,sans-serif;overflow:hidden}
+.tpa-panel.tpa-open{display:flex}
+.tpa-header{background:#1a73e8;color:#fff;padding:12px 14px;font-weight:600;display:flex;justify-content:space-between;align-items:center}
+.tpa-close{background:none;border:0;color:#fff;font-size:16px;cursor:pointer}
+.tpa-messages{flex:1;overflow-y:auto;padding:12px;display:flex;flex-direction:column;gap:8px;background:#f5f7fa}
+.tpa-msg{max-width:82%;padding:8px 12px;border-radius:14px;font-size:13px;line-height:1.45;white-space:pre-wrap;word-break:break-word}
+.tpa-user{align-self:flex-end;background:#1a73e8;color:#fff;border-bottom-right-radius:4px}
+.tpa-agent{align-self:flex-start;background:#fff;color:#222;border:1px solid #e3e6ea;border-bottom-left-radius:4px}
+.tpa-status{align-self:flex-start;color:#777;font-size:11px;font-style:italic;padding:0 4px}
+.tpa-confirm{align-self:flex-start;background:#fff8e6;border:1px solid #f0d489;border-radius:12px;padding:10px 12px;font-size:13px;max-width:88%}
+.tpa-confirm-actions{margin-top:8px;display:flex;gap:8px}
+.tpa-allow,.tpa-deny{border:0;border-radius:8px;padding:6px 14px;font-size:13px;cursor:pointer}
+.tpa-allow{background:#1a8f3c;color:#fff}
+.tpa-deny{background:#c0392b;color:#fff}
+.tpa-inputrow{display:flex;gap:8px;padding:10px;border-top:1px solid #e3e6ea;background:#fff}
+.tpa-input{flex:1;border:1px solid #cfd6dd;border-radius:10px;padding:8px 10px;font:inherit;font-size:13px}
+.tpa-send{border:0;border-radius:10px;background:#1a73e8;color:#fff;padding:8px 14px;cursor:pointer;font-size:13px}
+.tpa-send:disabled{background:#9db8dd;cursor:default}
+`
+
+export class ChatWidget {
+	#root = null
+	#messages = null
+	#input = null
+	#send = null
+	#panel = null
+	#onTask
+	#title
+	#pendingAsk = null // {resolve} — next send resolves an askUser instead of firing onTask
+
+	/**
+	 * @param {Object} cfg
+	 * @param {string} [cfg.title='Page Assistant']
+	 * @param {(task: string) => void} [cfg.onTask]  called when the user sends a message
+	 */
+	constructor(cfg = {}) {
+		this.#title = cfg.title ?? 'Page Assistant'
+		this.#onTask = cfg.onTask ?? (() => {})
+	}
+
+	mount(parent = document.body) {
+		if (this.#root) return this
+
+		if (!document.getElementById('tpa-style')) {
+			const style = document.createElement('style')
+			style.id = 'tpa-style'
+			style.textContent = STYLE
+			document.head.appendChild(style)
+		}
+
+		this.#root = document.createElement('div')
+
+		const bubble = document.createElement('button')
+		bubble.className = 'tpa-bubble'
+		bubble.setAttribute('aria-label', 'Open assistant')
+		bubble.textContent = '💬'
+		bubble.addEventListener('click', () => this.toggle())
+
+		this.#panel = document.createElement('div')
+		this.#panel.className = 'tpa-panel'
+
+		const header = document.createElement('div')
+		header.className = 'tpa-header'
+		const titleEl = document.createElement('span')
+		titleEl.textContent = this.#title
+		const close = document.createElement('button')
+		close.className = 'tpa-close'
+		close.setAttribute('aria-label', 'Close')
+		close.textContent = '✕'
+		close.addEventListener('click', () => this.toggle(false))
+		header.append(titleEl, close)
+
+		this.#messages = document.createElement('div')
+		this.#messages.className = 'tpa-messages'
+
+		const inputRow = document.createElement('div')
+		inputRow.className = 'tpa-inputrow'
+		this.#input = document.createElement('input')
+		this.#input.className = 'tpa-input'
+		this.#input.placeholder = 'Describe a task…'
+		this.#input.addEventListener('keydown', (e) => {
+			if (e.key === 'Enter') this.#submit()
+		})
+		this.#send = document.createElement('button')
+		this.#send.className = 'tpa-send'
+		this.#send.textContent = 'Send'
+		this.#send.addEventListener('click', () => this.#submit())
+		inputRow.append(this.#input, this.#send)
+
+		this.#panel.append(header, this.#messages, inputRow)
+		this.#root.append(bubble, this.#panel)
+		parent.appendChild(this.#root)
+		return this
+	}
+
+	toggle(force) {
+		const open = force ?? !this.#panel.classList.contains('tpa-open')
+		this.#panel.classList.toggle('tpa-open', open)
+	}
+
+	#submit() {
+		const text = this.#input.value.trim()
+		if (!text) return
+		this.#input.value = ''
+		this.addMessage('user', text)
+		if (this.#pendingAsk) {
+			const { resolve } = this.#pendingAsk
+			this.#pendingAsk = null
+			this.#input.placeholder = 'Describe a task…'
+			resolve(text)
+			return
+		}
+		this.#onTask(text)
+	}
+
+	/** Append a chat bubble. role: 'user' | 'agent'. XSS-safe (textContent). */
+	addMessage(role, text) {
+		const el = document.createElement('div')
+		el.className = `tpa-msg ${role === 'user' ? 'tpa-user' : 'tpa-agent'}`
+		el.textContent = text
+		this.#messages.appendChild(el)
+		this.#messages.scrollTop = this.#messages.scrollHeight
+		return el
+	}
+
+	/** Small italic status line ("step 2: clicking [3]…"). */
+	addStatus(text) {
+		const el = document.createElement('div')
+		el.className = 'tpa-status'
+		el.textContent = text
+		this.#messages.appendChild(el)
+		this.#messages.scrollTop = this.#messages.scrollHeight
+		return el
+	}
+
+	/** Render agent activity events (drop-in for onActivity). */
+	showActivity(ev) {
+		if (ev.type === 'thinking') this.addStatus(`step ${ev.step}: thinking…`)
+		if (ev.type === 'executing') this.addStatus(`step ${ev.step}: ${ev.actionName} — ${ev.nextGoal ?? ''}`)
+		if (ev.type === 'executed') this.addStatus(`→ ${ev.resultMessage}`)
+	}
+
+	/**
+	 * Human gate UI (drop-in for PolicyGuard onConfirm).
+	 * Resolves true only if the user clicks Allow.
+	 */
+	requestConfirm({ reason }) {
+		this.toggle(true)
+		return new Promise((resolve) => {
+			const box = document.createElement('div')
+			box.className = 'tpa-confirm'
+			const msg = document.createElement('div')
+			msg.textContent = `⚠️ Sensitive action needs your approval:\n${reason}`
+			const actions = document.createElement('div')
+			actions.className = 'tpa-confirm-actions'
+			const allow = document.createElement('button')
+			allow.className = 'tpa-allow'
+			allow.textContent = 'Allow'
+			const deny = document.createElement('button')
+			deny.className = 'tpa-deny'
+			deny.textContent = 'Deny'
+			const decide = (v) => {
+				actions.remove()
+				this.addStatus(v ? 'approved by you' : 'denied by you')
+				resolve(v)
+			}
+			allow.addEventListener('click', () => decide(true))
+			deny.addEventListener('click', () => decide(false))
+			actions.append(allow, deny)
+			box.append(msg, actions)
+			this.#messages.appendChild(box)
+			this.#messages.scrollTop = this.#messages.scrollHeight
+		})
+	}
+
+	/**
+	 * ask_user tool UI (drop-in for onAskUser): shows the question as an agent
+	 * bubble; the next message the user sends resolves it.
+	 */
+	askUser(question) {
+		this.toggle(true)
+		this.addMessage('agent', question)
+		this.#input.placeholder = 'Answer the question…'
+		return new Promise((resolve) => {
+			this.#pendingAsk = { resolve }
+		})
+	}
+
+	setBusy(busy) {
+		if (this.#send) this.#send.disabled = busy
+	}
+}