feat(m3.5): AI analyze — deterministic form fill + safety + bounded execute

[ralyodio]

Implements M3.5 — AI analyze (PRD §11) and wires the SDK page.analyze/step/runTask. Base main.

tron analyze                                   # describe the page's forms
tron analyze form --json                       # machine-readable form map
tron analyze "Fill this contact form" --data ./lead.json
tron analyze "..." --data ./lead.json --execute --no-submit
tron analyze "..." --data ./lead.json --execute --allow-submit

Design: deterministic where it can be

Form-fill analyze needs no LLM — it's label/name/placeholder/ARIA → data-path matching with a safety policy. So that path is fully built and tested; only open-ended navigation needs a model (returns AI_PROVIDER_NOT_CONFIGURED rather than guessing — the BYOK/local planner is a follow-up).

packages/agent-runtime/src/analyze

• data / matching — flatten --data to dot-paths; match fields with synonyms (e-mail→email, organization→company) + confidence. Plans reference lead.email, never the value (kept out of logs/traces).
• policy — credential/payment/PII fields (password, card, CVV, SSN, API key…) are never auto-filled; a submit needs --allow-submit; payment/irreversible submits (Pay, Delete account, Transfer) are blocked even with --allow-submit; a CAPTCHA stops the loop.
• form-script — in-page reader (refs from the snapshot's data-tron-ref, required, type, submit control).
• forms / planner — build a form map + safe ordered plan; report missing required data and ambiguous mappings instead of guessing.
• analyze — dry-run returns the plan; --execute fills low-risk fields then stops before the gated submit, bounded by --max-steps.
• analyze-cli / -bin — tron analyze with --data (file/inline/stdin), --execute, --no-submit, --allow-submit, --policy, --json.

Acceptance criteria (PRD §22)

• ✅ Dry-run by default.
• ✅ Maps labels/placeholders/ARIA/name to data with confidence.
• ✅ --execute fills low-risk fields; ✅ submit/risky require confirmation/policy.
• ✅ Low-confidence/ambiguous return options instead of guessing.
• ✅ Missing data / CAPTCHA / max-steps stop cleanly.

Wiring

• install.sh routes tron analyze via a new generic bin launcher (tron-node.mjs) that resolves agent-runtime's @tronbrowser/* imports (agent-runtime dist isn't self-contained like browser-core's).
• build-release.sh ships agent-runtime dist as analyze/; the SDK depends on agent-runtime and implements page.analyze/step/runTask.

Verification — +38 tests

• Units (matching/policy/data), the in-page form reader against a real DOM (happy-dom), the analyze orchestration (map + confidence, missing data, CAPTCHA, high-risk field never filled, execute+no-submit, allow-submit low-risk, high-risk submit refused, AI_PROVIDER_NOT_CONFIGURED), and the CLI with fakes.
• Manually verified tron analyze end-to-end (dry-run → 0.98 field mapping + gated submit; --execute --no-submit → 3 fills, stops before submit; --execute --allow-submit → fills + submit → complete) via a WS CDP stub through the full dispatcher → runtime → CDP path.
• Full workspace suite green in CI order (build → typecheck → test) from clean.

Scope

Deterministic form path is complete and tested. Open-ended LLM navigation is interface-only (needs a configured provider — untestable in CI). See docs/analyze.md.

🤖 Generated with Claude Code

[github-actions]

vu1nz Security Review

0 finding(s) in PR #?

No security issues found.