From 3e030fbbd931cb7f5862e13dfb1f2b454384f8ef Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 4 Jul 2026 13:05:24 +0000
Subject: [PATCH] =?UTF-8?q?feat(m3.5):=20AI=20analyze=20=E2=80=94=20determ?=
 =?UTF-8?q?inistic=20form=20fill=20+=20safety=20+=20bounded=20execute?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds `tron analyze` and wires the SDK page.analyze/step/runTask (PRD §11).
Dry-run by default; --execute runs a bounded, safety-gated fill loop.

  tron analyze "Fill this contact form" --data ./lead.json
  tron analyze "..." --data ./lead.json --execute --no-submit
  tron analyze form --json

packages/agent-runtime/src/analyze — deterministic, no LLM:
- data/matching: flatten --data to dot-paths; match label/name/placeholder/ARIA
  to data with synonyms + confidence (values referenced by path, never echoed).
- policy: risk classification — credential/payment/PII fields never auto-fill;
  submit needs --allow-submit; payment/irreversible submits blocked even then;
  CAPTCHA stops the loop.
- form-script: in-page reader (refs from the snapshot's data-tron-ref, required,
  type, submit). forms/planner: build a form map + safe ordered plan; report
  missing required data and ambiguous mappings instead of guessing.
- analyze: orchestration — 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.

Open-ended navigation goals return AI_PROVIDER_NOT_CONFIGURED (deterministic
form path is complete; the BYOK/local planner is a follow-up).

Wiring: install.sh routes `tron analyze` via a new generic bin launcher
(tron-node.mjs) that resolves agent-runtime's @tronbrowser/* imports; build-
release ships agent-runtime dist as analyze/; the SDK depends on agent-runtime
and implements page.analyze/step/runTask; tron-run resolver maps agent-runtime.

Tests (+38): matching/policy/data units, the in-page form reader (happy-dom),
the analyze orchestration (dry-run map, missing data, CAPTCHA, high-risk field
never filled, execute+no-submit, allow-submit, high-risk submit refused), and
the CLI with fakes. Verified `tron analyze` end-to-end (dry-run + execute) via a
WS CDP stub. Full workspace suite green in CI order.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/desktop/launcher/tron-node.mjs           |  26 ++++
 apps/desktop/launcher/tron-run.mjs            |   2 +
 apps/desktop/scripts/build-release.sh         |  14 +-
 apps/web/public/install.sh                    |   9 ++
 docs/analyze.md                               |  66 ++++++++
 packages/agent-runtime/package.json           |   4 +
 packages/agent-runtime/src/analyze-bin.ts     |  13 ++
 .../agent-runtime/src/analyze-cli.test.ts     |  88 +++++++++++
 packages/agent-runtime/src/analyze-cli.ts     | 145 ++++++++++++++++++
 .../agent-runtime/src/analyze/analyze.test.ts | 139 +++++++++++++++++
 packages/agent-runtime/src/analyze/analyze.ts | 129 ++++++++++++++++
 packages/agent-runtime/src/analyze/data.ts    |  40 +++++
 .../src/analyze/form-script.test.ts           |  66 ++++++++
 .../agent-runtime/src/analyze/form-script.ts  |  86 +++++++++++
 packages/agent-runtime/src/analyze/format.ts  |  48 ++++++
 packages/agent-runtime/src/analyze/forms.ts   |  43 ++++++
 packages/agent-runtime/src/analyze/index.ts   |  13 ++
 .../agent-runtime/src/analyze/matching.ts     |  81 ++++++++++
 packages/agent-runtime/src/analyze/planner.ts |  94 ++++++++++++
 packages/agent-runtime/src/analyze/policy.ts  |  70 +++++++++
 packages/agent-runtime/src/analyze/types.ts   |  94 ++++++++++++
 .../agent-runtime/src/analyze/units.test.ts   |  67 ++++++++
 packages/agent-runtime/src/index.ts           |   3 +
 packages/sdk/package.json                     |   1 +
 packages/sdk/src/index.ts                     |   9 ++
 packages/sdk/src/page.ts                      |  43 ++++--
 packages/sdk/src/sdk.test.ts                  |   9 +-
 pnpm-lock.yaml                                |  10 ++
 28 files changed, 1393 insertions(+), 19 deletions(-)
 create mode 100644 apps/desktop/launcher/tron-node.mjs
 create mode 100644 docs/analyze.md
 create mode 100644 packages/agent-runtime/src/analyze-bin.ts
 create mode 100644 packages/agent-runtime/src/analyze-cli.test.ts
 create mode 100644 packages/agent-runtime/src/analyze-cli.ts
 create mode 100644 packages/agent-runtime/src/analyze/analyze.test.ts
 create mode 100644 packages/agent-runtime/src/analyze/analyze.ts
 create mode 100644 packages/agent-runtime/src/analyze/data.ts
 create mode 100644 packages/agent-runtime/src/analyze/form-script.test.ts
 create mode 100644 packages/agent-runtime/src/analyze/form-script.ts
 create mode 100644 packages/agent-runtime/src/analyze/format.ts
 create mode 100644 packages/agent-runtime/src/analyze/forms.ts
 create mode 100644 packages/agent-runtime/src/analyze/index.ts
 create mode 100644 packages/agent-runtime/src/analyze/matching.ts
 create mode 100644 packages/agent-runtime/src/analyze/planner.ts
 create mode 100644 packages/agent-runtime/src/analyze/policy.ts
 create mode 100644 packages/agent-runtime/src/analyze/types.ts
 create mode 100644 packages/agent-runtime/src/analyze/units.test.ts

diff --git a/apps/desktop/launcher/tron-node.mjs b/apps/desktop/launcher/tron-node.mjs
new file mode 100644
index 0000000..06d56e0
--- /dev/null
+++ b/apps/desktop/launcher/tron-node.mjs
@@ -0,0 +1,26 @@
+// Generic launcher for shipped Node bins that import @tronbrowser/* packages by
+// bare specifier (e.g. analyze-bin -> @tronbrowser/browser-core). Registers the
+// resolver hook that maps those specifiers to the sibling dist trees in the
+// launcher payload, then runs the target entry.
+//
+//   node tron-node.mjs <entry.js> [args...]
+import { register } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+register(pathToFileURL(join(here, 'tron-run-hooks.mjs')), import.meta.url, {
+  data: {
+    '@tronbrowser/browser-core': pathToFileURL(join(here, 'automate', 'index.js')).href,
+    '@tronbrowser/agent-runtime': pathToFileURL(join(here, 'analyze', 'index.js')).href,
+    '@tronbrowser/sdk': pathToFileURL(join(here, 'sdk', 'index.js')).href,
+  },
+});
+
+const entry = process.argv[2];
+if (!entry) {
+  process.stderr.write('tron-node: missing entry\n');
+  process.exit(2);
+}
+process.argv = [process.argv[0], entry, ...process.argv.slice(3)];
+await import(pathToFileURL(entry).href);
diff --git a/apps/desktop/launcher/tron-run.mjs b/apps/desktop/launcher/tron-run.mjs
index 4111e3e..4c0bd9f 100644
--- a/apps/desktop/launcher/tron-run.mjs
+++ b/apps/desktop/launcher/tron-run.mjs
@@ -10,6 +10,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const here = dirname(fileURLToPath(import.meta.url));
 const sdkEntry = join(here, 'sdk', 'index.js');
 const coreEntry = join(here, 'automate', 'index.js');
+const agentEntry = join(here, 'analyze', 'index.js');
 
 const argv = process.argv.slice(2);
 let script;
@@ -43,6 +44,7 @@ register(pathToFileURL(join(here, 'tron-run-hooks.mjs')), import.meta.url, {
   data: {
     '@tronbrowser/sdk': pathToFileURL(sdkEntry).href,
     '@tronbrowser/browser-core': pathToFileURL(coreEntry).href,
+    '@tronbrowser/agent-runtime': pathToFileURL(agentEntry).href,
   },
 });
 
diff --git a/apps/desktop/scripts/build-release.sh b/apps/desktop/scripts/build-release.sh
index b8a1304..98a50f1 100755
--- a/apps/desktop/scripts/build-release.sh
+++ b/apps/desktop/scripts/build-release.sh
@@ -61,15 +61,17 @@ stage_automation() { # dest dir
   local s="$1"
   command -v node >/dev/null 2>&1 && command -v pnpm >/dev/null 2>&1 || {
     echo "  ! automation runtime skipped (needs node + pnpm)"; return; }
-  if ( cd "$REPO_ROOT" && pnpm --filter @tronbrowser/browser-core --filter @tronbrowser/sdk build >/dev/null 2>&1 ); then
-    rm -rf "$s/automate" "$s/sdk"
+  if ( cd "$REPO_ROOT" && pnpm --filter @tronbrowser/browser-core --filter @tronbrowser/agent-runtime --filter @tronbrowser/sdk build >/dev/null 2>&1 ); then
+    rm -rf "$s/automate" "$s/analyze" "$s/sdk"
     cp -R "$REPO_ROOT/packages/browser-core/dist" "$s/automate"
     printf '{\n  "type": "module"\n}\n' > "$s/automate/package.json"
+    cp -R "$REPO_ROOT/packages/agent-runtime/dist" "$s/analyze"
+    printf '{\n  "type": "module"\n}\n' > "$s/analyze/package.json"
     cp -R "$REPO_ROOT/packages/sdk/dist" "$s/sdk"
     printf '{\n  "type": "module"\n}\n' > "$s/sdk/package.json"
-    echo "  + bundled automation runtime + SDK (tron snapshot/extract/run)"
+    echo "  + bundled automation + analyze + SDK (tron snapshot/extract/analyze/run)"
   else
-    echo "  ! automation runtime skipped (browser-core/sdk build failed)"
+    echo "  ! automation runtime skipped (browser-core/agent-runtime/sdk build failed)"
   fi
 }
 
@@ -84,9 +86,11 @@ stage() { # dest dir
   # Managed-session engine for `tron browser …` / `tron open` (PRD M3.1). Sits
   # next to the shim; the `tron` dispatcher resolves it relative to $CURRENT.
   install -m 0755 "$DESKTOP/launcher/tron-session" "$s/tron-session"
-  # `tron run` launcher + ESM resolver hook (PRD M3.4).
+  # `tron run` launcher + ESM resolver hook (PRD M3.4) and the generic bin
+  # launcher used by `tron analyze` (PRD M3.5).
   install -m 0644 "$DESKTOP/launcher/tron-run.mjs" "$s/tron-run.mjs"
   install -m 0644 "$DESKTOP/launcher/tron-run-hooks.mjs" "$s/tron-run-hooks.mjs"
+  install -m 0644 "$DESKTOP/launcher/tron-node.mjs" "$s/tron-node.mjs"
   stage_automation "$s"
   # -L dereferences the branding symlinks (icons/logo.svg -> repo-root logo.svg)
   # so the package contains real files, not dangling links.
diff --git a/apps/web/public/install.sh b/apps/web/public/install.sh
index 94945fa..ecf2d94 100755
--- a/apps/web/public/install.sh
+++ b/apps/web/public/install.sh
@@ -91,6 +91,7 @@ Usage:
   tron screenshot <p>   Save a PNG of the current page (--full-page)
   tron headless <url>   One-shot: --snapshot | --screenshot <p> | --extract <mode>
   tron run <script>     Run a JS/TS script using @tronbrowser/sdk (--headless/--trace)
+  tron analyze [goal]   Analyze/fill a form or page (--data, --execute, --json)
   tron upgrade          Update to the latest release
   tron remove           Uninstall TronBrowser (keeps your profile data)
   tron version          Print the installed version
@@ -176,6 +177,14 @@ case "${1:-}" in
   snapshot|click|fill|type|extract|screenshot|pdf)
     # CDP automation on the managed session's current page (PRD M3.2/M3.3).
     run_automation "$@" ;;
+  analyze)
+    # AI-assisted unknown-interface analysis / form fill (PRD M3.5). Runs via
+    # tron-node.mjs so agent-runtime's @tronbrowser/* imports resolve.
+    _ld="$(dirname "$(readlink -f "$CURRENT" 2>/dev/null || echo "$CURRENT")")"
+    ENTRY="$_ld/analyze/analyze-bin.js"
+    command -v node >/dev/null 2>&1 || { echo "tron analyze needs Node.js (>=22) on PATH." >&2; exit 1; }
+    [ -f "$ENTRY" ] || { echo "This TronBrowser build lacks the analyze runtime. Run: tron upgrade" >&2; exit 1; }
+    exec node "$_ld/tron-node.mjs" "$ENTRY" "$@" ;;
   headless)
     # One-shot: launch a headless ephemeral session, navigate, act, tear down.
     run_automation "$@" ;;
diff --git a/docs/analyze.md b/docs/analyze.md
new file mode 100644
index 0000000..1d7f07f
--- /dev/null
+++ b/docs/analyze.md
@@ -0,0 +1,66 @@
+# AI analyze (M3.5)
+
+`tron analyze` inspects the current page of a managed session and answers "what
+is this asking for, and what should I do next?" — mapping forms to your data,
+proposing a safe plan, and (with `--execute`) filling low-risk fields under a
+strict safety policy. **Dry-run by default.**
+
+```sh
+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 "Fill this contact form but do not submit" --data ./lead.json --execute --no-submit
+tron analyze "Fill and submit" --data ./lead.json --execute --allow-submit
+```
+
+`--data` accepts a file, inline JSON, or `-` (stdin):
+
+```json
+{ "lead": { "name": "Jane Doe", "email": "jane@example.com", "message": "Please send pricing." } }
+```
+
+## What it does
+
+- **Maps fields to data** deterministically: labels/placeholders/ARIA/`name` are
+  matched to your data paths (synonyms like *e-mail → email*, *organization →
+  company*) with a confidence score. Plans reference `lead.email`, never the
+  value — so values stay out of logs and traces.
+- **Reports missing required data** and **ambiguous** mappings instead of
+  guessing.
+- **Safety policy** (`--policy safe|auto|ask`, default `safe`):
+  - Credential/payment/PII fields (password, card, CVV, SSN, API key…) are
+    **never auto-filled**.
+  - A final submit needs `--allow-submit`; `--no-submit` fills but never submits.
+  - Payment/irreversible submits (*Pay*, *Delete account*, *Transfer*…) are
+    **blocked even with `--allow-submit`**.
+  - A CAPTCHA/challenge stops the loop.
+- **`--execute`** runs a bounded (`--max-steps`, default 8), validated loop:
+  fill low-risk fields, then stop before the gated submit. Stale refs, missing
+  data, ambiguity, challenges, and max-steps all end the loop cleanly.
+
+## Output
+
+Text by default; `--json` for a machine-readable `AnalyzeResult` (status,
+`detectedForms`, `plan`, `nextAction`, `missingData`, `ambiguous`, `reason`).
+Statuses: `planned`, `acted`, `complete`, `needs_confirmation`, `blocked`,
+`ambiguous`, `failed`.
+
+## From the SDK
+
+```ts
+const result = await page.analyze('Fill contact form', { data: lead });      // dry-run
+await page.analyze('Fill contact form', { data: lead, execute: true, noSubmit: true });
+```
+
+`page.step()` runs one bounded step; `page.runTask()` runs the loop to
+completion.
+
+## Scope
+
+- The **form-fill path is deterministic** (no LLM) and fully covered by tests.
+- **Open-ended navigation** goals (e.g. "click through onboarding until the
+  dashboard") need a configured AI provider; without one, analyze returns
+  `AI_PROVIDER_NOT_CONFIGURED` rather than guessing. Wiring the BYOK/local
+  provider planner is a follow-up.
+- Requires Node ≥22 and a running managed session (`tron browser launch`).
+- Logic lives in `packages/agent-runtime/src/analyze`.
diff --git a/packages/agent-runtime/package.json b/packages/agent-runtime/package.json
index e709f7a..65c78dd 100644
--- a/packages/agent-runtime/package.json
+++ b/packages/agent-runtime/package.json
@@ -18,7 +18,11 @@
     "test": "vitest run --passWithNoTests",
     "lint": "eslint src"
   },
+  "dependencies": {
+    "@tronbrowser/browser-core": "workspace:*"
+  },
   "devDependencies": {
+    "happy-dom": "^20.10.6",
     "typescript": "^5.6.3",
     "vitest": "^2.1.4"
   }
diff --git a/packages/agent-runtime/src/analyze-bin.ts b/packages/agent-runtime/src/analyze-bin.ts
new file mode 100644
index 0000000..a69669c
--- /dev/null
+++ b/packages/agent-runtime/src/analyze-bin.ts
@@ -0,0 +1,13 @@
+/**
+ * Executable wrapper for `tron analyze`. Built into the launcher payload as
+ * `analyze/analyze-bin.js`; the shell dispatcher runs it via node.
+ */
+import { run } from './analyze-cli.js';
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err: unknown) => {
+    process.stderr.write(`tron: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  },
+);
diff --git a/packages/agent-runtime/src/analyze-cli.test.ts b/packages/agent-runtime/src/analyze-cli.test.ts
new file mode 100644
index 0000000..a0c1cb7
--- /dev/null
+++ b/packages/agent-runtime/src/analyze-cli.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest';
+import { EXIT, run, type AnalyzeCliDeps } from './analyze-cli.js';
+import type { AnalyzeBrowser } from './analyze/analyze.js';
+import type { RawFormsResult } from './analyze/form-script.js';
+
+const contactForm: RawFormsResult = {
+  challenge: false,
+  forms: [{ name: 'contact', submitRef: '@e4', submitLabel: 'Send', fields: [
+    { ref: '@e1', label: 'Name', name: 'name', type: 'text', role: 'input', required: true },
+    { ref: '@e2', label: 'Email', name: 'email', type: 'email', role: 'input', required: true },
+  ] }],
+};
+const lead = { lead: { name: 'Jane', email: 'jane@example.com' } };
+
+function browser(raw: RawFormsResult, hooks: Partial<AnalyzeBrowser> = {}): AnalyzeBrowser {
+  return {
+    snapshot: async () => ({ url: 'https://x/contact', title: 'Contact', timestamp: 't', elements: [] }),
+    readForms: async () => raw,
+    fill: hooks.fill ?? (async () => {}),
+    click: hooks.click ?? (async () => {}),
+  };
+}
+
+function harness(overrides: Partial<AnalyzeCliDeps> = {}, raw = contactForm) {
+  const out: string[] = [];
+  const err: string[] = [];
+  const close = vi.fn();
+  const deps: Partial<AnalyzeCliDeps> = {
+    env: {},
+    attach: async () => ({ browser: browser(raw), close }),
+    readData: async () => lead,
+    out: (t) => out.push(t),
+    err: (t) => err.push(t),
+    ...overrides,
+  };
+  return { deps, out, err, close };
+}
+
+describe('analyze CLI', () => {
+  it('prints a JSON plan and closes the session', async () => {
+    const { deps, out, close } = harness();
+    const code = await run(['Fill contact form', '--data', './lead.json', '--json'], deps);
+    expect(code).toBe(EXIT.ok);
+    const result = JSON.parse(out.join('\n'));
+    expect(result.status).toBe('planned');
+    expect(result.detectedForms[0].fields[1].valueFrom).toBe('lead.email');
+    expect(close).toHaveBeenCalled();
+  });
+
+  it('treats a bare mode keyword as mode, not a goal', async () => {
+    const { deps, out } = harness();
+    await run(['form', '--json'], deps);
+    expect(JSON.parse(out.join('\n')).goal).toBeUndefined();
+  });
+
+  it('exits notOk (6) when required data is missing', async () => {
+    const { deps } = harness({ readData: async () => ({ lead: { name: 'Jane' } }) });
+    expect(await run(['Fill', '--data', 'x', '--json'], deps)).toBe(EXIT.notOk);
+  });
+
+  it('exits noSession (4) when no managed session', async () => {
+    const { deps, err } = harness({
+      attach: async () => {
+        const e = new Error('No managed session. Run: tron browser launch') as Error & { exit?: number };
+        e.exit = EXIT.noSession;
+        throw e;
+      },
+    });
+    const code = await run(['form'], deps);
+    expect(code).toBe(EXIT.noSession);
+    expect(err.join('\n')).toContain('tron browser launch');
+  });
+
+  it('executes fills but not submit with --execute --no-submit', async () => {
+    const fill = vi.fn(async () => {});
+    const click = vi.fn(async () => {});
+    const { deps } = harness({ attach: async () => ({ browser: browser(contactForm, { fill, click }), close: vi.fn() }) });
+    const code = await run(['Fill', '--data', 'x', '--execute', '--no-submit', '--json'], deps);
+    expect(code).toBe(EXIT.ok);
+    expect(fill).toHaveBeenCalledTimes(2);
+    expect(click).not.toHaveBeenCalled();
+  });
+
+  it('rejects an invalid --policy', async () => {
+    const { deps } = harness();
+    expect(await run(['form', '--policy', 'wild'], deps)).toBe(EXIT.usage);
+  });
+});
diff --git a/packages/agent-runtime/src/analyze-cli.ts b/packages/agent-runtime/src/analyze-cli.ts
new file mode 100644
index 0000000..28258f2
--- /dev/null
+++ b/packages/agent-runtime/src/analyze-cli.ts
@@ -0,0 +1,145 @@
+/**
+ * `tron analyze` — the AI-assisted unknown-interface command (PRD §11). Dry-run
+ * by default; `--execute` runs a bounded, safety-gated fill loop. Attaches to the
+ * managed session and drives it via CDP. Deps are injectable for testing.
+ */
+import { readFile } from 'node:fs/promises';
+import {
+  captureSnapshot,
+  CdpClient,
+  cdpListUrl,
+  clickRef,
+  descriptorPath,
+  enableRuntime,
+  extract,
+  fillRef,
+  parseDescriptor,
+  resolveDataDir,
+  resolvePageWsUrl,
+  type CdpTarget,
+  type SessionDescriptor,
+} from '@tronbrowser/browser-core';
+import { analyze, type AnalyzeBrowser, type AnalyzeOptions } from './analyze/analyze.js';
+import { analyzeFormsExpression, type RawFormsResult } from './analyze/form-script.js';
+import { formatAnalyzeText } from './analyze/format.js';
+import type { Policy } from './analyze/types.js';
+
+export const EXIT = { ok: 0, usage: 2, noSession: 4, notOk: 6, failed: 1 } as const;
+
+const MODES = new Set(['form', 'plan', 'next', 'run']);
+const POLICIES = new Set(['safe', 'auto', 'ask']);
+
+export interface AnalyzeCliDeps {
+  env: NodeJS.ProcessEnv;
+  attach(dataDir: string): Promise<{ browser: AnalyzeBrowser; close(): void }>;
+  readData(spec: string): Promise<unknown>;
+  out(text: string): void;
+  err(text: string): void;
+}
+
+async function fetchTargets(host: string, port: number): Promise<CdpTarget[]> {
+  const res = await fetch(cdpListUrl({ host, port }));
+  if (!res.ok) throw new Error(`DevTools /json/list returned ${res.status}`);
+  return (await res.json()) as CdpTarget[];
+}
+
+const defaultDeps: AnalyzeCliDeps = {
+  env: process.env,
+  async attach(dataDir) {
+    let descriptor: SessionDescriptor;
+    try {
+      descriptor = parseDescriptor(await readFile(descriptorPath(dataDir), 'utf8'));
+    } catch {
+      const e = new Error('No managed session. Run: tron browser launch') as Error & { exit?: number };
+      e.exit = EXIT.noSession;
+      throw e;
+    }
+    const targets = await fetchTargets(descriptor.host, descriptor.port);
+    const conn = await CdpClient.connect(resolvePageWsUrl(targets, descriptor.activeTabId));
+    await enableRuntime(conn);
+    const browser: AnalyzeBrowser = {
+      snapshot: () => captureSnapshot(conn),
+      readForms: () => extract<RawFormsResult>(conn, analyzeFormsExpression()),
+      fill: async (ref, value) => {
+        await fillRef(conn, ref, value);
+      },
+      click: async (ref) => {
+        await clickRef(conn, ref);
+      },
+    };
+    return { browser, close: () => conn.close() };
+  },
+  async readData(spec) {
+    if (spec === '-') return JSON.parse(await readStdin());
+    const trimmed = spec.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) return JSON.parse(trimmed);
+    return JSON.parse(await readFile(spec, 'utf8'));
+  },
+  out: (t) => process.stdout.write(t + '\n'),
+  err: (t) => process.stderr.write(t + '\n'),
+};
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function valueAfter(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+export async function run(argv: string[], overrides: Partial<AnalyzeCliDeps> = {}): Promise<number> {
+  const deps: AnalyzeCliDeps = { ...defaultDeps, ...overrides };
+  const json = argv.includes('--json');
+
+  // First positional is a goal, unless it's a bare mode keyword.
+  const positional = argv.find((a) => !a.startsWith('--'));
+  const goal = positional && !MODES.has(positional) ? positional : undefined;
+
+  const options: AnalyzeOptions = {
+    ...(goal ? { goal } : {}),
+    execute: argv.includes('--execute') && !argv.includes('--dry-run'),
+    noSubmit: argv.includes('--no-submit'),
+    allowSubmit: argv.includes('--allow-submit'),
+  };
+  const policy = valueAfter(argv, '--policy');
+  if (policy) {
+    if (!POLICIES.has(policy)) {
+      deps.err(`usage: --policy must be safe|auto|ask`);
+      return EXIT.usage;
+    }
+    options.policy = policy as Policy;
+  }
+  const maxSteps = valueAfter(argv, '--max-steps');
+  if (maxSteps) options.maxSteps = Number(maxSteps);
+
+  const dataSpec = valueAfter(argv, '--data');
+  if (dataSpec) {
+    try {
+      options.data = await deps.readData(dataSpec);
+    } catch (err) {
+      deps.err(`tron analyze: could not read --data: ${(err as Error).message}`);
+      return EXIT.usage;
+    }
+  }
+
+  let session: { browser: AnalyzeBrowser; close(): void } | undefined;
+  try {
+    session = await deps.attach(resolveDataDir(deps.env));
+    const result = await analyze(session.browser, options);
+    deps.out(json ? JSON.stringify(result, null, 2) : formatAnalyzeText(result));
+    return result.ok ? EXIT.ok : EXIT.notOk;
+  } catch (err) {
+    const coded = err as Error & { exit?: number };
+    deps.err(`tron: ${coded.message}`);
+    return typeof coded.exit === 'number' ? coded.exit : EXIT.failed;
+  } finally {
+    session?.close();
+  }
+}
diff --git a/packages/agent-runtime/src/analyze/analyze.test.ts b/packages/agent-runtime/src/analyze/analyze.test.ts
new file mode 100644
index 0000000..9124668
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/analyze.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it, vi } from 'vitest';
+import { analyze, type AnalyzeBrowser } from './analyze.js';
+import type { RawField, RawFormsResult } from './form-script.js';
+
+function field(ref: string, label: string, name: string, type: string, required = false): RawField {
+  return { ref, label, name, type, role: type === 'textarea' ? 'textarea' : 'input', required };
+}
+
+const contactForm: RawFormsResult = {
+  challenge: false,
+  forms: [
+    {
+      name: 'contact',
+      submitRef: '@e6',
+      submitLabel: 'Send',
+      fields: [
+        field('@e2', 'Name', 'name', 'text', true),
+        field('@e3', 'Email', 'email', 'email', true),
+        field('@e4', 'Company', 'company', 'text'),
+        field('@e5', 'Message', 'message', 'textarea', true),
+      ],
+    },
+  ],
+};
+
+const lead = { lead: { name: 'Jane Doe', email: 'jane@example.com', company: 'Acme', message: 'Hello' } };
+
+function fakeBrowser(raw: RawFormsResult, hooks: Partial<AnalyzeBrowser> = {}): AnalyzeBrowser {
+  return {
+    snapshot: async () => ({ url: 'https://x/contact', title: 'Contact', timestamp: 't', elements: [] }),
+    readForms: async () => raw,
+    fill: hooks.fill ?? (async () => {}),
+    click: hooks.click ?? (async () => {}),
+  };
+}
+
+describe('analyze — dry run', () => {
+  it('maps fields to data with confidence and gates the submit', async () => {
+    const r = await analyze(fakeBrowser(contactForm), { goal: 'Fill contact form', data: lead });
+    expect(r.status).toBe('planned');
+    expect(r.ok).toBe(true);
+    const emails = r.detectedForms![0].fields.find((f) => f.label === 'Email')!;
+    expect(emails.valueFrom).toBe('lead.email');
+    expect(emails.confidence).toBeGreaterThan(0.9);
+    // 4 fills + 1 gated submit
+    expect(r.plan!.filter((a) => a.action === 'fill')).toHaveLength(4);
+    const submit = r.plan!.find((a) => a.action === 'submit')!;
+    expect(submit.blockedReason).toMatch(/--allow-submit/);
+    expect(r.nextAction!.target).toBe('@e2');
+    expect(r.missingData).toHaveLength(0);
+  });
+
+  it('blocks on missing required data', async () => {
+    const r = await analyze(fakeBrowser(contactForm), {
+      data: { lead: { name: 'Jane', email: 'jane@example.com', company: 'Acme' } }, // no message
+    });
+    expect(r.status).toBe('blocked');
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe('MISSING_REQUIRED_DATA');
+    expect(r.missingData!.map((m) => m.label)).toContain('Message');
+  });
+
+  it('stops on a CAPTCHA/challenge', async () => {
+    const r = await analyze(fakeBrowser({ challenge: true, forms: [] }), { data: lead });
+    expect(r.status).toBe('blocked');
+    expect(r.reason).toBe('CAPTCHA_OR_CHALLENGE_DETECTED');
+  });
+
+  it('never maps data into a high-risk field', async () => {
+    const login: RawFormsResult = {
+      challenge: false,
+      forms: [{ name: 'login', submitRef: '@e3', submitLabel: 'Sign in', fields: [
+        field('@e1', 'Email', 'email', 'email', true),
+        field('@e2', 'Password', 'password', 'password', true),
+      ] }],
+    };
+    const r = await analyze(fakeBrowser(login), { data: { lead: { email: 'a@b.com', password: 'hunter2' } } });
+    const pw = r.detectedForms![0].fields.find((f) => f.label === 'Password')!;
+    expect(pw.valueFrom).toBeUndefined();
+    expect(r.plan!.some((a) => a.target === '@e2')).toBe(false); // password never in the plan
+  });
+});
+
+describe('analyze — execute', () => {
+  it('fills low-risk fields but stops before submit with --no-submit', async () => {
+    const fill = vi.fn(async () => {});
+    const click = vi.fn(async () => {});
+    const r = await analyze(fakeBrowser(contactForm, { fill, click }), {
+      goal: 'Fill contact form', data: lead, execute: true, noSubmit: true,
+    });
+    expect(fill).toHaveBeenCalledTimes(4);
+    expect(click).not.toHaveBeenCalled();
+    expect(r.status).toBe('needs_confirmation');
+    expect(r.executed).toHaveLength(4);
+  });
+
+  it('submits an ordinary low-risk form with --allow-submit', async () => {
+    const click = vi.fn(async () => {});
+    const r = await analyze(fakeBrowser(contactForm, { click }), {
+      data: lead, execute: true, allowSubmit: true,
+    });
+    expect(click).toHaveBeenCalledWith('@e6');
+    expect(r.status).toBe('complete');
+  });
+
+  it('refuses a high-risk submit even with --allow-submit', async () => {
+    const payment: RawFormsResult = {
+      challenge: false,
+      forms: [{ name: 'checkout', submitRef: '@e2', submitLabel: 'Pay now', fields: [
+        field('@e1', 'Full name', 'name', 'text', true),
+      ] }],
+    };
+    const click = vi.fn(async () => {});
+    const r = await analyze(fakeBrowser(payment, { click }), {
+      data: { lead: { name: 'Jane Doe' } }, execute: true, allowSubmit: true,
+    });
+    expect(click).not.toHaveBeenCalled();
+    expect(r.status).toBe('needs_confirmation');
+    expect(r.plan!.find((a) => a.action === 'submit')!.risk).toBe('high');
+  });
+
+  it('reports fill values from data paths (never echoing them in the plan)', async () => {
+    const seen: Array<[string, string]> = [];
+    await analyze(fakeBrowser(contactForm, { fill: async (r, v) => { seen.push([r, v]); } }), {
+      data: lead, execute: true, noSubmit: true,
+    });
+    expect(seen).toContainEqual(['@e3', 'jane@example.com']);
+  });
+});
+
+describe('analyze — free-form goal without data', () => {
+  it('reports AI_PROVIDER_NOT_CONFIGURED when there is nothing to fill', async () => {
+    const r = await analyze(fakeBrowser({ challenge: false, forms: [] }), {
+      goal: 'Click through onboarding until the dashboard', execute: true,
+    });
+    expect(r.status).toBe('blocked');
+    expect(r.reason).toBe('AI_PROVIDER_NOT_CONFIGURED');
+  });
+});
diff --git a/packages/agent-runtime/src/analyze/analyze.ts b/packages/agent-runtime/src/analyze/analyze.ts
new file mode 100644
index 0000000..cd32651
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/analyze.ts
@@ -0,0 +1,129 @@
+/**
+ * Analyze orchestration (PRD §11). Dry-run by default: inspect the page, map
+ * forms to data, and return a plan. With `execute`, run a bounded, validated
+ * fill loop that stops before any gated submit, on missing data, ambiguity, a
+ * challenge, or max steps — never guessing.
+ */
+import type { AgentSnapshot } from '@tronbrowser/browser-core';
+import type { RawFormsResult } from './form-script.js';
+import { buildForms } from './forms.js';
+import { getByPath } from './data.js';
+import { planForm } from './planner.js';
+import { ANALYZE_ERROR, type AnalyzeResult, type PlannedAction, type Policy } from './types.js';
+
+/** The browser operations analyze needs. The CLI wires these to CDP; tests fake them. */
+export interface AnalyzeBrowser {
+  /** Snapshot the page (must tag elements with data-tron-ref). */
+  snapshot(): Promise<AgentSnapshot>;
+  /** Read forms (evaluate analyzeFormsExpression) after a snapshot. */
+  readForms(): Promise<RawFormsResult>;
+  fill(ref: string, value: string): Promise<void>;
+  click(ref: string): Promise<void>;
+}
+
+export interface AnalyzeOptions {
+  goal?: string;
+  data?: unknown;
+  execute?: boolean;
+  noSubmit?: boolean;
+  allowSubmit?: boolean;
+  policy?: Policy;
+  maxSteps?: number;
+}
+
+export async function analyze(browser: AnalyzeBrowser, options: AnalyzeOptions = {}): Promise<AnalyzeResult> {
+  const execute = options.execute === true;
+  const opts = {
+    policy: options.policy ?? 'safe',
+    noSubmit: options.noSubmit === true,
+    allowSubmit: options.allowSubmit === true,
+    maxSteps: options.maxSteps ?? 8,
+  };
+
+  const snap = await browser.snapshot();
+  const page = { url: snap.url, title: snap.title };
+  const raw = await browser.readForms();
+
+  const base = (): AnalyzeResult => ({
+    ok: true,
+    mode: execute ? 'execute' : 'dry-run',
+    status: 'planned',
+    ...(options.goal ? { goal: options.goal } : {}),
+    page,
+  });
+
+  if (raw.challenge) {
+    return {
+      ...base(),
+      ok: false,
+      status: 'blocked',
+      reason: ANALYZE_ERROR.CAPTCHA_OR_CHALLENGE_DETECTED,
+      message: 'A CAPTCHA or anti-abuse challenge is present; stopping.',
+    };
+  }
+
+  const forms = buildForms(raw, options.data ?? {});
+  const hasFillable = forms.some((f) => f.fields.some((x) => x.valueFrom || x.missing));
+
+  // A free-form goal with nothing to fill needs a reasoning planner (M3.5 wires
+  // the deterministic form path; open-ended navigation needs a configured provider).
+  if (options.goal && !hasFillable && forms.every((f) => f.fields.length === 0)) {
+    return {
+      ...base(),
+      ok: false,
+      status: 'blocked',
+      reason: ANALYZE_ERROR.AI_PROVIDER_NOT_CONFIGURED,
+      message: 'This goal needs an AI provider for open-ended navigation; none is configured.',
+    };
+  }
+
+  const fp = planForm(forms, opts);
+  const result: AnalyzeResult = {
+    ...base(),
+    status: fp.status,
+    detectedForms: forms,
+    plan: fp.plan,
+    nextAction: fp.nextAction,
+    missingData: fp.missingData,
+    ambiguous: fp.ambiguous,
+    confidence: fp.confidence,
+  };
+
+  if (fp.status === 'blocked') {
+    return { ...result, ok: false, reason: ANALYZE_ERROR.MISSING_REQUIRED_DATA, message: 'Required fields have no matching data.' };
+  }
+  if (fp.status === 'ambiguous') {
+    return { ...result, ok: false, reason: ANALYZE_ERROR.AMBIGUOUS_TARGET, message: 'Multiple fields map to the same data; resolve before proceeding.' };
+  }
+
+  if (!execute) return result;
+
+  // Bounded execute: fill, then gate the submit.
+  const executed: PlannedAction[] = [];
+  let steps = 0;
+  for (const action of fp.plan) {
+    if (steps >= opts.maxSteps) {
+      return { ...result, ok: false, status: 'blocked', reason: ANALYZE_ERROR.MAX_STEPS_REACHED, executed };
+    }
+    if (action.action === 'fill' && action.valueFrom) {
+      const value = getByPath(options.data, action.valueFrom);
+      try {
+        await browser.fill(action.target, value === undefined || value === null ? '' : String(value));
+      } catch (err) {
+        return { ...result, ok: false, status: 'blocked', message: (err as Error).message, executed };
+      }
+      executed.push(action);
+      steps += 1;
+    } else if (action.action === 'submit') {
+      if (action.blockedReason) {
+        return { ...result, status: 'needs_confirmation', nextAction: action, executed, message: action.blockedReason };
+      }
+      await browser.click(action.target);
+      executed.push(action);
+      return { ...result, status: 'complete', executed };
+    }
+  }
+
+  const status = fp.plan.some((a) => a.action === 'submit') ? 'needs_confirmation' : 'complete';
+  return { ...result, status, executed, nextAction: null };
+}
diff --git a/packages/agent-runtime/src/analyze/data.ts b/packages/agent-runtime/src/analyze/data.ts
new file mode 100644
index 0000000..30dd565
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/data.ts
@@ -0,0 +1,40 @@
+/**
+ * User data handling for analyze (PRD §11.4). Flattens the `--data` JSON to
+ * dot-paths so fields can reference `lead.email` instead of echoing values —
+ * keeping sensitive values out of plans, logs, and traces.
+ */
+
+export type DataLeaf = { path: string; value: string };
+
+/** Flatten an object to `{ "a.b.c": "value" }` for primitive leaves. */
+export function flattenData(data: unknown, prefix = ''): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (data === null || data === undefined) return out;
+  if (typeof data !== 'object') {
+    if (prefix) out[prefix] = String(data);
+    return out;
+  }
+  if (Array.isArray(data)) {
+    data.forEach((v, i) => Object.assign(out, flattenData(v, prefix ? `${prefix}.${i}` : String(i))));
+    return out;
+  }
+  for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+    Object.assign(out, flattenData(v, prefix ? `${prefix}.${k}` : k));
+  }
+  return out;
+}
+
+/** Resolve a dot-path against the data object (used at execute time). */
+export function getByPath(data: unknown, path: string): unknown {
+  return path.split('.').reduce<unknown>((acc, key) => {
+    if (acc !== null && typeof acc === 'object') {
+      return (acc as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, data);
+}
+
+/** The list of leaves as {path, value}. */
+export function dataLeaves(data: unknown): DataLeaf[] {
+  return Object.entries(flattenData(data)).map(([path, value]) => ({ path, value }));
+}
diff --git a/packages/agent-runtime/src/analyze/form-script.test.ts b/packages/agent-runtime/src/analyze/form-script.test.ts
new file mode 100644
index 0000000..60e67ec
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/form-script.test.ts
@@ -0,0 +1,66 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it } from 'vitest';
+import { analyzeFormsExpression, type RawFormsResult } from './form-script.js';
+
+function run(expr: string): RawFormsResult {
+  return new Function('return ' + expr)() as RawFormsResult;
+}
+
+// The analyze form-reader relies on data-tron-ref being set (by a prior snapshot);
+// tag elements here to simulate that.
+function tagRefs(): void {
+  let n = 0;
+  for (const el of document.querySelectorAll('input, textarea, select, button')) {
+    n += 1;
+    el.setAttribute('data-tron-ref', `e${n}`);
+  }
+}
+
+beforeEach(() => {
+  document.head.innerHTML = '';
+  document.body.innerHTML = '';
+});
+
+describe('analyzeFormsExpression', () => {
+  it('reads fields with refs, labels, types, required, and the submit control', () => {
+    document.body.innerHTML = `
+      <form name="contact">
+        <label for="n">Name</label><input id="n" name="name" required />
+        <label for="e">Email</label><input id="e" name="email" type="email" required />
+        <textarea aria-label="Message"></textarea>
+        <input type="hidden" name="csrf" />
+        <button type="submit">Send</button>
+      </form>`;
+    tagRefs();
+    const res = run(analyzeFormsExpression());
+    expect(res.forms).toHaveLength(1);
+    const form = res.forms[0];
+    expect(form.name).toBe('contact');
+    expect(form.submitLabel).toBe('Send');
+    expect(form.fields.map((f) => f.label)).toEqual(['Name', 'Email', 'Message']); // hidden excluded
+    const email = form.fields.find((f) => f.label === 'Email')!;
+    expect(email.type).toBe('email');
+    expect(email.required).toBe(true);
+    expect(email.ref).toMatch(/^@e\d+$/);
+    expect(form.submitRef).toMatch(/^@e\d+$/);
+  });
+
+  it('synthesizes a form for fields outside any <form>', () => {
+    document.body.innerHTML = `
+      <div>
+        <label for="e">Email</label><input id="e" name="email" />
+        <button>Subscribe</button>
+      </div>`;
+    tagRefs();
+    const res = run(analyzeFormsExpression());
+    expect(res.forms).toHaveLength(1);
+    expect(res.forms[0].name).toBe('page');
+    expect(res.forms[0].fields[0].label).toBe('Email');
+  });
+
+  it('detects a captcha challenge', () => {
+    document.body.innerHTML = `<form><input name="x"/></form><div class="g-recaptcha"></div>`;
+    tagRefs();
+    expect(run(analyzeFormsExpression()).challenge).toBe(true);
+  });
+});
diff --git a/packages/agent-runtime/src/analyze/form-script.ts b/packages/agent-runtime/src/analyze/form-script.ts
new file mode 100644
index 0000000..bad7910
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/form-script.ts
@@ -0,0 +1,86 @@
+/**
+ * In-page form reader for analyze (PRD M3.5). Runs after a snapshot has tagged
+ * elements with `data-tron-ref`, so each field/submit carries a stable ref. It
+ * returns labels, input types, required flags, and submit controls — the raw
+ * material the deterministic matcher/planner turn into a form map + plan.
+ */
+
+/** Raw field as read from the page. */
+export interface RawField {
+  ref: string;
+  label: string;
+  name: string;
+  type: string;
+  role: string;
+  required: boolean;
+}
+
+/** Raw form as read from the page. */
+export interface RawForm {
+  name: string;
+  submitRef?: string;
+  submitLabel?: string;
+  fields: RawField[];
+}
+
+export interface RawFormsResult {
+  forms: RawForm[];
+  challenge: boolean;
+}
+
+/** Build the expression evaluated via CDP Runtime.evaluate. */
+export function analyzeFormsExpression(): string {
+  return `(() => {
+  const REF = 'data-tron-ref';
+  const refOf = (el) => el.hasAttribute(REF) ? ('@' + el.getAttribute(REF)) : '';
+  const clean = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+  const labelFor = (el) => {
+    try { if (el.id) { const l = document.querySelector('label[for="' + (typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(el.id) : el.id) + '"]'); if (l) return clean(l.textContent); } } catch (_) {}
+    const w = el.closest('label'); if (w) return clean(w.textContent);
+    return '';
+  };
+  const nameOf = (el) => labelFor(el) || el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.getAttribute('name') || '';
+  const typeOf = (el) => {
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'textarea') return 'textarea';
+    if (tag === 'select') return 'select';
+    return (el.getAttribute('type') || 'text').toLowerCase();
+  };
+  const isRequired = (el) => el.hasAttribute('required') || el.getAttribute('aria-required') === 'true';
+  const isField = (el) => {
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'textarea' || tag === 'select') return true;
+    if (tag !== 'input') return false;
+    return !['hidden', 'submit', 'button', 'reset', 'image'].includes(typeOf(el));
+  };
+  const fieldOf = (el) => ({
+    ref: refOf(el), label: nameOf(el), name: el.getAttribute('name') || '',
+    type: typeOf(el), role: el.tagName.toLowerCase(), required: isRequired(el),
+  });
+  const submitOf = (form) => {
+    const btn = form.querySelector('button[type=submit], input[type=submit], button:not([type])')
+      || [...form.querySelectorAll('button, input[type=button]')].find((b) => /submit|send|save|continue|next|sign|register|subscribe|request/i.test(clean(b.textContent) + ' ' + (b.value || '')));
+    return btn ? { submitRef: refOf(btn), submitLabel: clean(btn.textContent) || btn.value || 'Submit' } : {};
+  };
+
+  const forms = [...document.querySelectorAll('form')].map((f) => ({
+    name: f.getAttribute('name') || f.getAttribute('aria-label') || f.id || 'form',
+    ...submitOf(f),
+    fields: [...f.querySelectorAll('input, textarea, select')].filter(isField).map(fieldOf),
+  })).filter((f) => f.fields.length > 0);
+
+  // Fields outside any <form> (common in SPAs) -> one synthetic form.
+  if (forms.length === 0) {
+    const loose = [...document.querySelectorAll('input, textarea, select')].filter((el) => isField(el) && !el.closest('form'));
+    if (loose.length > 0) {
+      const btn = [...document.querySelectorAll('button, input[type=submit]')].find((b) => /submit|send|save|continue|next|sign|register|subscribe|request/i.test(clean(b.textContent) + ' ' + (b.value || '')));
+      forms.push({ name: 'page', submitRef: btn ? refOf(btn) : undefined, submitLabel: btn ? (clean(btn.textContent) || btn.value) : undefined, fields: loose.map(fieldOf) });
+    }
+  }
+
+  const bodyText = (document.body ? document.body.textContent || '' : '').toLowerCase();
+  const challenge = /captcha|recaptcha|hcaptcha|are you human/.test(bodyText) || !!document.querySelector('iframe[src*="recaptcha"], iframe[src*="hcaptcha"], .g-recaptcha, .h-captcha');
+
+  return { forms, challenge };
+})()`;
+}
diff --git a/packages/agent-runtime/src/analyze/format.ts b/packages/agent-runtime/src/analyze/format.ts
new file mode 100644
index 0000000..2572ee9
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/format.ts
@@ -0,0 +1,48 @@
+/**
+ * Human-readable rendering of an AnalyzeResult (PRD §11.5).
+ */
+import type { AnalyzeResult } from './types.js';
+
+export function formatAnalyzeText(r: AnalyzeResult): string {
+  const lines: string[] = [];
+  if (r.goal) lines.push(`Goal: ${r.goal}`);
+  lines.push(`Page: ${r.page.title || '(untitled)'}`);
+  lines.push(`URL: ${r.page.url}`);
+  lines.push('');
+
+  for (const form of r.detectedForms ?? []) {
+    lines.push(`Detected form: ${form.name}${form.submitLabel ? ` (submit: "${form.submitLabel}")` : ''}`);
+    for (const f of form.fields) {
+      const mapping = f.valueFrom
+        ? `<- ${f.valueFrom}   confidence ${f.confidence.toFixed(2)}`
+        : f.missing
+          ? '<- (missing data)'
+          : '';
+      lines.push(`  ${f.target} ${f.role} "${f.label}"${f.required ? ' *' : ''}  ${mapping}`.trimEnd());
+    }
+    lines.push('');
+  }
+
+  if (r.plan && r.plan.length) {
+    lines.push('Proposed plan:');
+    for (const a of r.plan) {
+      if (a.action === 'fill') lines.push(`  ${a.step}. Fill ${a.target} from ${a.valueFrom}`);
+      else if (a.action === 'submit') {
+        lines.push(`  ${a.step}. ${a.blockedReason ? `Stop before ${a.target} "${a.label}" — ${a.blockedReason}` : `Submit ${a.target} "${a.label}"`}`);
+      } else lines.push(`  ${a.step}. ${a.action} ${a.target}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`Missing data: ${r.missingData && r.missingData.length ? r.missingData.map((m) => `${m.label} (${m.target})`).join(', ') : 'none'}`);
+  if (r.ambiguous && r.ambiguous.length) lines.push(`Ambiguous: ${r.ambiguous.map((a) => a.reason).join('; ')}`);
+  if (r.risk) lines.push(`Risk: ${r.risk}`);
+  lines.push(`Status: ${r.status}${r.reason ? ` (${r.reason})` : ''}`);
+  if (r.message) lines.push(r.message);
+  if (r.nextAction) {
+    const n = r.nextAction;
+    lines.push(`Next action: ${n.action} ${n.target}${n.valueFrom ? ` from ${n.valueFrom}` : ''}`);
+  }
+  if (r.executed && r.executed.length) lines.push(`Executed: ${r.executed.map((a) => `${a.action} ${a.target}`).join(', ')}`);
+  return lines.join('\n');
+}
diff --git a/packages/agent-runtime/src/analyze/forms.ts b/packages/agent-runtime/src/analyze/forms.ts
new file mode 100644
index 0000000..2312dc3
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/forms.ts
@@ -0,0 +1,43 @@
+/**
+ * Turn raw page forms + user data into a mapped form model (PRD §11.5/11.6).
+ * High-risk fields are never matched to data (never auto-filled).
+ */
+import { dataLeaves } from './data.js';
+import type { RawForm, RawFormsResult } from './form-script.js';
+import { matchField, MATCH_THRESHOLD } from './matching.js';
+import { fieldRisk } from './policy.js';
+import type { DetectedForm, FormFieldMapping } from './types.js';
+
+export function buildForms(raw: RawFormsResult, data: unknown): DetectedForm[] {
+  const leaves = dataLeaves(data);
+  return raw.forms.map((f, i) => buildForm(f, i + 1, leaves));
+}
+
+function buildForm(f: RawForm, index: number, leaves: ReturnType<typeof dataLeaves>): DetectedForm {
+  const fields = f.fields.map((field): FormFieldMapping => {
+    const risk = fieldRisk(`${field.label} ${field.name} ${field.type}`);
+    const match =
+      risk === 'high'
+        ? { confidence: 0 as number, path: undefined as string | undefined }
+        : matchField({ label: field.label, name: field.name, placeholder: '', type: field.type }, leaves);
+    const path = match.path;
+    const matched = path !== undefined && match.confidence >= MATCH_THRESHOLD;
+    return {
+      target: field.ref,
+      label: field.label || field.name || '(unlabeled)',
+      role: field.role,
+      type: field.type,
+      required: field.required,
+      ...(path !== undefined && matched ? { valueFrom: path } : {}),
+      confidence: matched ? match.confidence : 0,
+      missing: field.required && !matched && risk !== 'high',
+    };
+  });
+  return {
+    ref: `@form${index}`,
+    name: f.name,
+    ...(f.submitRef ? { submitRef: f.submitRef } : {}),
+    ...(f.submitLabel ? { submitLabel: f.submitLabel } : {}),
+    fields,
+  };
+}
diff --git a/packages/agent-runtime/src/analyze/index.ts b/packages/agent-runtime/src/analyze/index.ts
new file mode 100644
index 0000000..e09d40f
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/index.ts
@@ -0,0 +1,13 @@
+/**
+ * @tronbrowser/agent-runtime — analyze (PRD M3.5).
+ * Deterministic form-fill analysis + safety policy + bounded execution.
+ */
+export * from './types.js';
+export * from './data.js';
+export * from './matching.js';
+export * from './policy.js';
+export * from './form-script.js';
+export * from './forms.js';
+export * from './planner.js';
+export * from './analyze.js';
+export * from './format.js';
diff --git a/packages/agent-runtime/src/analyze/matching.ts b/packages/agent-runtime/src/analyze/matching.ts
new file mode 100644
index 0000000..f8c0a05
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/matching.ts
@@ -0,0 +1,81 @@
+/**
+ * Deterministic field ↔ data matching (PRD §11 acceptance: map labels/
+ * placeholders/ARIA/name to provided JSON data with confidence scores). No LLM.
+ */
+import type { DataLeaf } from './data.js';
+
+export interface FieldInfo {
+  label: string;
+  name: string;
+  placeholder: string;
+  type: string;
+}
+
+/** Synonym groups: field vocabulary → canonical key that data keys also map to. */
+const SYNONYMS: Record<string, string[]> = {
+  email: ['email', 'emailaddress', 'mail', 'youremail'],
+  name: ['name', 'fullname', 'yourname', 'contactname'],
+  firstname: ['firstname', 'fname', 'givenname', 'first'],
+  lastname: ['lastname', 'lname', 'surname', 'familyname', 'last'],
+  phone: ['phone', 'tel', 'telephone', 'mobile', 'cell', 'phonenumber'],
+  company: ['company', 'organization', 'organisation', 'business', 'employer', 'companyname'],
+  message: ['message', 'comments', 'comment', 'notes', 'details', 'inquiry', 'enquiry', 'body'],
+  subject: ['subject', 'topic', 'regarding'],
+  address: ['address', 'street', 'streetaddress', 'address1'],
+  city: ['city', 'town'],
+  state: ['state', 'province', 'region'],
+  zip: ['zip', 'zipcode', 'postal', 'postalcode', 'postcode'],
+  country: ['country', 'nation'],
+  website: ['website', 'url', 'site', 'web', 'homepage'],
+  title: ['title', 'jobtitle', 'role', 'position'],
+};
+
+export function normalize(s: string): string {
+  return (s || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/** Map a normalized token to its canonical synonym key (or itself). */
+export function canonical(norm: string): string {
+  for (const [canon, syns] of Object.entries(SYNONYMS)) {
+    if (canon === norm || syns.includes(norm)) return canon;
+  }
+  return norm;
+}
+
+export interface FieldMatch {
+  path?: string;
+  confidence: number;
+  /** A close runner-up, if any — used to flag ambiguous mappings. */
+  runnerUp?: { path: string; confidence: number };
+}
+
+/** Best data path for a field, with a confidence in [0,1]. */
+export function matchField(field: FieldInfo, leaves: readonly DataLeaf[]): FieldMatch {
+  const forms = [field.label, field.name, field.placeholder].map(normalize).filter(Boolean);
+  if (forms.length === 0 || leaves.length === 0) return { confidence: 0 };
+  const fieldCanons = new Set(forms.map(canonical));
+
+  const scored = leaves
+    .map((leaf) => {
+      const leafKey = normalize(leaf.path.split('.').pop() ?? leaf.path);
+      const leafCanon = canonical(leafKey);
+      let s = 0;
+      if (forms.includes(leafKey)) s = 0.98;
+      else if (fieldCanons.has(leafCanon)) s = 0.95;
+      else if (forms.some((f) => f === leafCanon)) s = 0.9;
+      else if (forms.some((f) => f.includes(leafKey) || leafKey.includes(f))) s = 0.78;
+      else if (fieldCanons.has(leafKey) || forms.some((f) => canonical(f) === leafCanon)) s = 0.7;
+      return { path: leaf.path, confidence: s };
+    })
+    .sort((a, b) => b.confidence - a.confidence);
+
+  const best = scored[0];
+  if (!best || best.confidence === 0) return { confidence: 0 };
+  const result: FieldMatch = { path: best.path, confidence: best.confidence };
+  const second = scored[1];
+  if (second && second.confidence > 0) result.runnerUp = { path: second.path, confidence: second.confidence };
+  return result;
+}
+
+/** Below this, treat a field as unmatched (no confident data). */
+export const MATCH_THRESHOLD = 0.55;
diff --git a/packages/agent-runtime/src/analyze/planner.ts b/packages/agent-runtime/src/analyze/planner.ts
new file mode 100644
index 0000000..ff00c60
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/planner.ts
@@ -0,0 +1,94 @@
+/**
+ * Deterministic form planner (PRD §11.5–11.6): builds a safe, ordered plan from
+ * the mapped forms and the safety policy. Fills matched low-risk fields, gates
+ * the submit, reports missing required data and ambiguous mappings.
+ */
+import { decideSubmit, submitRisk } from './policy.js';
+import type {
+  Ambiguity,
+  AnalyzeStatus,
+  DetectedForm,
+  MissingDatum,
+  PlannedAction,
+  Policy,
+} from './types.js';
+
+export interface PlanOptions {
+  policy: Policy;
+  noSubmit: boolean;
+  allowSubmit: boolean;
+}
+
+export interface FormPlan {
+  plan: PlannedAction[];
+  missingData: MissingDatum[];
+  ambiguous: Ambiguity[];
+  nextAction: PlannedAction | null;
+  status: AnalyzeStatus;
+  confidence: number;
+}
+
+export function planForm(forms: readonly DetectedForm[], options: PlanOptions): FormPlan {
+  const plan: PlannedAction[] = [];
+  const missingData: MissingDatum[] = [];
+  const ambiguous: Ambiguity[] = [];
+  const fillConfidences: number[] = [];
+  let step = 0;
+
+  for (const form of forms) {
+    const usedPaths = new Map<string, string[]>(); // data path -> field labels
+    for (const field of form.fields) {
+      if (field.valueFrom) {
+        plan.push({
+          step: ++step,
+          action: 'fill',
+          target: field.target,
+          label: field.label,
+          valueFrom: field.valueFrom,
+          risk: 'low',
+          confidence: field.confidence,
+          requiresConfirmation: false,
+        });
+        fillConfidences.push(field.confidence);
+        const labels = usedPaths.get(field.valueFrom) ?? [];
+        labels.push(field.label);
+        usedPaths.set(field.valueFrom, labels);
+      } else if (field.missing) {
+        missingData.push({ field: field.label, label: field.label, target: field.target });
+      }
+    }
+
+    // Two fields drawing from the same data path is ambiguous.
+    for (const [path, labels] of usedPaths) {
+      if (labels.length > 1) {
+        ambiguous.push({ reason: `Multiple fields map to ${path}`, options: labels });
+      }
+    }
+
+    if (form.submitRef) {
+      const risk = submitRisk(`${form.submitLabel ?? ''} ${form.name}`);
+      const decision = decideSubmit(risk, options);
+      plan.push({
+        step: ++step,
+        action: 'submit',
+        target: form.submitRef,
+        label: form.submitLabel ?? 'Submit',
+        risk,
+        confidence: 0.9,
+        requiresConfirmation: decision.requiresConfirmation,
+        ...(decision.blockedReason ? { blockedReason: decision.blockedReason } : {}),
+      });
+    }
+  }
+
+  let status: AnalyzeStatus = 'planned';
+  if (missingData.length > 0) status = 'blocked';
+  else if (ambiguous.length > 0) status = 'ambiguous';
+
+  const nextAction = status === 'planned' ? plan.find((a) => a.action === 'fill') ?? null : null;
+  const confidence = fillConfidences.length
+    ? Number((fillConfidences.reduce((a, b) => a + b, 0) / fillConfidences.length).toFixed(2))
+    : 0;
+
+  return { plan, missingData, ambiguous, nextAction, status, confidence };
+}
diff --git a/packages/agent-runtime/src/analyze/policy.ts b/packages/agent-runtime/src/analyze/policy.ts
new file mode 100644
index 0000000..a112c29
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/policy.ts
@@ -0,0 +1,70 @@
+/**
+ * Safety policy for analyze (PRD §11.3, §20). Classifies field/submit risk and
+ * decides what is allowed under the active policy + flags. Errs on the safe side:
+ * anything payment/credential/PII-sensitive is high-risk and blocked by default.
+ */
+import type { Policy, Risk } from './types.js';
+
+function lower(s: string): string {
+  return (s || '').toLowerCase();
+}
+
+/** Fields that must never be auto-filled or must block a submit. */
+const HIGH_RISK_FIELD = [
+  /pass\s?word/, /passwd/, /\bpin\b/, /\botp\b/, /mfa/, /2fa/, /one[-\s]?time/,
+  /card\s?number/, /credit\s?card/, /\bcvv\b/, /\bcvc\b/, /\bccv\b/, /security\s?code/,
+  /\bssn\b/, /social\s?security/, /\biban\b/, /routing/, /account\s?number/, /sort\s?code/,
+  /api[-\s]?key/, /secret/, /passphrase/, /seed\s?phrase/,
+];
+
+/** Submit/actions that are irreversible or move money — block even with --allow-submit. */
+const HIGH_RISK_SUBMIT = [
+  /\bpay\b/, /payment/, /purchase/, /checkout/, /\bbuy\b/, /place\s?order/, /donate/,
+  /transfer/, /withdraw/, /\bwire\b/, /delete\s?account/, /close\s?account/, /deactivate/,
+  /cancel\s?subscription/, /change\s?password/, /reset\s?password/, /disable\s?2fa/,
+];
+
+/** Anti-abuse challenges that must stop the loop. */
+const CHALLENGE = [/captcha/, /recaptcha/, /hcaptcha/, /are\s?you\s?human/, /verify\s?you.?re\s?human/];
+
+export function fieldRisk(text: string): Risk {
+  const t = lower(text);
+  return HIGH_RISK_FIELD.some((r) => r.test(t)) ? 'high' : 'low';
+}
+
+export function submitRisk(text: string): Risk {
+  const t = lower(text);
+  if (HIGH_RISK_SUBMIT.some((r) => r.test(t))) return 'high';
+  return 'medium'; // any final submit is at least medium
+}
+
+export function looksLikeChallenge(text: string): boolean {
+  return CHALLENGE.some((r) => r.test(lower(text)));
+}
+
+/** May a low-/high-risk field be filled given the policy? (high never auto-fills). */
+export function canFill(risk: Risk): boolean {
+  return risk === 'low';
+}
+
+export interface SubmitDecision {
+  allowed: boolean;
+  requiresConfirmation: boolean;
+  blockedReason?: string;
+}
+
+/**
+ * Decide whether a form submit may proceed.
+ * - high-risk submit: always blocked (even with --allow-submit).
+ * - otherwise: needs --allow-submit; under `ask` policy it prompts.
+ */
+export function decideSubmit(risk: Risk, opts: { allowSubmit: boolean; noSubmit: boolean; policy: Policy }): SubmitDecision {
+  if (opts.noSubmit) return { allowed: false, requiresConfirmation: false, blockedReason: '--no-submit set' };
+  if (risk === 'high') {
+    return { allowed: false, requiresConfirmation: true, blockedReason: 'High-risk submit (payment/credential/irreversible) requires explicit confirmation' };
+  }
+  if (!opts.allowSubmit) {
+    return { allowed: false, requiresConfirmation: true, blockedReason: 'Final submit requires --allow-submit' };
+  }
+  return { allowed: true, requiresConfirmation: opts.policy === 'ask' };
+}
diff --git a/packages/agent-runtime/src/analyze/types.ts b/packages/agent-runtime/src/analyze/types.ts
new file mode 100644
index 0000000..82777b6
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/types.ts
@@ -0,0 +1,94 @@
+/**
+ * AI-analyze contracts (PRD M3.5 / §11). The form-mapping + safety path is
+ * deterministic; an optional Planner handles open-ended goals.
+ */
+
+export type Risk = 'low' | 'medium' | 'high';
+export type Policy = 'safe' | 'auto' | 'ask';
+export type AnalyzeMode = 'plan' | 'form' | 'next' | 'run';
+
+export type AnalyzeStatus =
+  | 'planned'
+  | 'acted'
+  | 'complete'
+  | 'blocked'
+  | 'needs_confirmation'
+  | 'ambiguous'
+  | 'failed';
+
+/** Coded reasons for blocked/failed results (PRD §18). */
+export const ANALYZE_ERROR = {
+  AI_PROVIDER_NOT_CONFIGURED: 'AI_PROVIDER_NOT_CONFIGURED',
+  MISSING_REQUIRED_DATA: 'MISSING_REQUIRED_DATA',
+  LOW_CONFIDENCE_ACTION: 'LOW_CONFIDENCE_ACTION',
+  ACTION_REQUIRES_CONFIRMATION: 'ACTION_REQUIRES_CONFIRMATION',
+  UNSAFE_ACTION_BLOCKED: 'UNSAFE_ACTION_BLOCKED',
+  MAX_STEPS_REACHED: 'MAX_STEPS_REACHED',
+  GOAL_NOT_VERIFIED: 'GOAL_NOT_VERIFIED',
+  CAPTCHA_OR_CHALLENGE_DETECTED: 'CAPTCHA_OR_CHALLENGE_DETECTED',
+  AMBIGUOUS_TARGET: 'AMBIGUOUS_TARGET',
+} as const;
+export type AnalyzeErrorCode = (typeof ANALYZE_ERROR)[keyof typeof ANALYZE_ERROR];
+
+export type ActionKind = 'fill' | 'click' | 'submit' | 'navigate' | 'stop';
+
+export interface PlannedAction {
+  step: number;
+  action: ActionKind;
+  target: string; // @ref
+  label: string;
+  valueFrom?: string; // data path, e.g. "lead.email" — never a literal value
+  risk: Risk;
+  confidence: number;
+  requiresConfirmation: boolean;
+  blockedReason?: string;
+}
+
+export interface FormFieldMapping {
+  target: string; // @ref
+  label: string;
+  role: string;
+  type: string;
+  required: boolean;
+  valueFrom?: string; // matched data path
+  confidence: number;
+  missing: boolean; // required but no data matched
+}
+
+export interface DetectedForm {
+  ref: string; // synthetic id, e.g. "@form1"
+  name: string;
+  submitRef?: string;
+  submitLabel?: string;
+  fields: FormFieldMapping[];
+}
+
+export interface MissingDatum {
+  field: string;
+  label: string;
+  target: string;
+}
+
+export interface Ambiguity {
+  reason: string;
+  options: string[];
+}
+
+export interface AnalyzeResult {
+  ok: boolean;
+  mode: 'dry-run' | 'execute';
+  status: AnalyzeStatus;
+  goal?: string;
+  page: { url: string; title: string };
+  detectedForms?: DetectedForm[];
+  missingData?: MissingDatum[];
+  ambiguous?: Ambiguity[];
+  plan?: PlannedAction[];
+  nextAction?: PlannedAction | null;
+  reason?: AnalyzeErrorCode;
+  message?: string;
+  risk?: Risk;
+  confidence?: number;
+  executed?: PlannedAction[];
+  traceId?: string;
+}
diff --git a/packages/agent-runtime/src/analyze/units.test.ts b/packages/agent-runtime/src/analyze/units.test.ts
new file mode 100644
index 0000000..dd19896
--- /dev/null
+++ b/packages/agent-runtime/src/analyze/units.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { dataLeaves, flattenData, getByPath } from './data.js';
+import { canonical, matchField, MATCH_THRESHOLD, normalize } from './matching.js';
+import { decideSubmit, fieldRisk, looksLikeChallenge, submitRisk } from './policy.js';
+
+describe('data', () => {
+  it('flattens nested objects to dot-paths', () => {
+    expect(flattenData({ lead: { email: 'a@b.com', n: 2 } })).toEqual({ 'lead.email': 'a@b.com', 'lead.n': '2' });
+  });
+  it('resolves a path', () => {
+    expect(getByPath({ lead: { email: 'a@b.com' } }, 'lead.email')).toBe('a@b.com');
+    expect(getByPath({ lead: {} }, 'lead.missing')).toBeUndefined();
+  });
+});
+
+describe('matching', () => {
+  const leaves = dataLeaves({ lead: { name: 'Jane', email: 'jane@x.com', company: 'Acme', message: 'Hi' } });
+  it('normalizes and canonicalizes synonyms', () => {
+    expect(normalize('E-mail Address')).toBe('emailaddress');
+    expect(canonical('emailaddress')).toBe('email');
+    expect(canonical('organisation')).toBe('company');
+  });
+  it('matches by exact key, synonym, and label', () => {
+    expect(matchField({ label: 'Email', name: 'email', placeholder: '', type: 'email' }, leaves).path).toBe('lead.email');
+    expect(matchField({ label: 'Your e-mail', name: '', placeholder: '', type: 'text' }, leaves).path).toBe('lead.email');
+    expect(matchField({ label: 'Organization', name: 'org', placeholder: '', type: 'text' }, leaves).path).toBe('lead.company');
+  });
+  it('returns low confidence for unrelated fields', () => {
+    const m = matchField({ label: 'Favorite color', name: 'color', placeholder: '', type: 'text' }, leaves);
+    expect(m.confidence).toBeLessThan(MATCH_THRESHOLD);
+  });
+});
+
+describe('policy', () => {
+  it('flags credential/payment fields as high risk', () => {
+    expect(fieldRisk('Password')).toBe('high');
+    expect(fieldRisk('Card number')).toBe('high');
+    expect(fieldRisk('CVV')).toBe('high');
+    expect(fieldRisk('Email')).toBe('low');
+  });
+  it('rates submits: payment/irreversible = high, ordinary = medium', () => {
+    expect(submitRisk('Pay now')).toBe('high');
+    expect(submitRisk('Delete account')).toBe('high');
+    expect(submitRisk('Send message')).toBe('medium');
+  });
+  it('detects challenges', () => {
+    expect(looksLikeChallenge('Please complete the reCAPTCHA')).toBe(true);
+    expect(looksLikeChallenge('Contact us')).toBe(false);
+  });
+  describe('decideSubmit', () => {
+    const base = { policy: 'safe' as const };
+    it('blocks without --allow-submit', () => {
+      const d = decideSubmit('medium', { ...base, allowSubmit: false, noSubmit: false });
+      expect(d.allowed).toBe(false);
+      expect(d.blockedReason).toMatch(/--allow-submit/);
+    });
+    it('allows an ordinary submit with --allow-submit', () => {
+      expect(decideSubmit('medium', { ...base, allowSubmit: true, noSubmit: false }).allowed).toBe(true);
+    });
+    it('never allows a high-risk submit', () => {
+      expect(decideSubmit('high', { ...base, allowSubmit: true, noSubmit: false }).allowed).toBe(false);
+    });
+    it('respects --no-submit', () => {
+      expect(decideSubmit('medium', { ...base, allowSubmit: true, noSubmit: true }).allowed).toBe(false);
+    });
+  });
+});
diff --git a/packages/agent-runtime/src/index.ts b/packages/agent-runtime/src/index.ts
index 575e1b5..a20d68f 100644
--- a/packages/agent-runtime/src/index.ts
+++ b/packages/agent-runtime/src/index.ts
@@ -6,6 +6,9 @@
 
 export const PACKAGE_NAME = '@tronbrowser/agent-runtime' as const;
 
+// AI analyze — form-fill + safety + bounded execution (PRD M3.5).
+export * from './analyze/index.js';
+
 export interface Goal {
   id: string;
   description: string;
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index ae73f92..52b82dd 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -19,6 +19,7 @@
     "lint": "eslint src"
   },
   "dependencies": {
+    "@tronbrowser/agent-runtime": "workspace:*",
     "@tronbrowser/browser-core": "workspace:*"
   },
   "devDependencies": {
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 2428fc4..db9e70b 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -26,6 +26,15 @@ export type {
   FieldSpec,
 } from '@tronbrowser/browser-core';
 
+// Analyze types (PRD M3.5) for page.analyze()/step()/runTask().
+export type {
+  AnalyzeResult,
+  AnalyzeOptions,
+  PlannedAction,
+  DetectedForm,
+  FormFieldMapping,
+} from '@tronbrowser/agent-runtime';
+
 import { Browser, type LaunchOptions } from './browser.js';
 import type { SdkDeps } from './deps.js';
 
diff --git a/packages/sdk/src/page.ts b/packages/sdk/src/page.ts
index 1d80f16..64f87b2 100644
--- a/packages/sdk/src/page.ts
+++ b/packages/sdk/src/page.ts
@@ -20,13 +20,16 @@ import {
   type ScreenshotOptions,
   type SnapshotOptions,
 } from '@tronbrowser/browser-core';
+import {
+  analyze,
+  analyzeFormsExpression,
+  type AnalyzeBrowser,
+  type AnalyzeOptions,
+  type AnalyzeResult,
+  type RawFormsResult,
+} from '@tronbrowser/agent-runtime';
 import type { Tracer } from './trace.js';
 
-/** Analyze/step/runTask land in M3.5; the surface exists so scripts type-check. */
-function notYet(name: string): never {
-  throw new Error(`page.${name}() arrives in M3.5 (AI analyze). Not available yet.`);
-}
-
 export class Page {
   readonly #conn: CdpConnection;
   readonly #tracer: Tracer | undefined;
@@ -118,14 +121,32 @@ export class Page {
     return this.eval<string>('document.title');
   }
 
-  analyze(): never {
-    return notYet('analyze');
+  /** Adapter exposing this page to the analyze runtime. */
+  #analyzeBrowser(): AnalyzeBrowser {
+    return {
+      snapshot: () => this.snapshot(),
+      readForms: () => this.eval<RawFormsResult>(analyzeFormsExpression()),
+      fill: (ref, value) => this.fill(ref, value),
+      click: (ref) => this.click(ref),
+    };
   }
-  step(): never {
-    return notYet('step');
+
+  /** Analyze the page / map a form to data (dry-run unless `execute`). */
+  analyze(goal?: string, options: AnalyzeOptions = {}): Promise<AnalyzeResult> {
+    this.#tracer?.record('analyze', goal);
+    return analyze(this.#analyzeBrowser(), { ...options, ...(goal ? { goal } : {}) });
   }
-  runTask(): never {
-    return notYet('runTask');
+
+  /** One bounded step toward a goal (execute, capped). */
+  step(goal: string, options: AnalyzeOptions = {}): Promise<AnalyzeResult> {
+    this.#tracer?.record('step', goal);
+    return analyze(this.#analyzeBrowser(), { ...options, goal, execute: true, maxSteps: 1 });
+  }
+
+  /** Run the bounded analyze loop to completion for a goal. */
+  runTask(goal: string, options: AnalyzeOptions = {}): Promise<AnalyzeResult> {
+    this.#tracer?.record('runTask', goal);
+    return analyze(this.#analyzeBrowser(), { ...options, goal, execute: true });
   }
 
   /** @internal */
diff --git a/packages/sdk/src/sdk.test.ts b/packages/sdk/src/sdk.test.ts
index 86fa25a..a75a72a 100644
--- a/packages/sdk/src/sdk.test.ts
+++ b/packages/sdk/src/sdk.test.ts
@@ -104,11 +104,14 @@ describe('tron.launch lifecycle', () => {
     await browser.close();
   });
 
-  it('surfaces analyze() as an M3.5 feature', async () => {
-    const { deps } = fakeDeps(fakeConn(null));
+  it('analyzes the page via the analyze runtime', async () => {
+    // Runtime.evaluate returns a forms result (readForms); snapshot only needs url/title.
+    const { deps } = fakeDeps(fakeConn({ challenge: false, forms: [] }));
     const browser = await tron.launch({}, deps);
     const page = await browser.newPage();
-    expect(() => page.analyze()).toThrow(/M3\.5/);
+    const result = await page.analyze('Fill contact form');
+    expect(result.mode).toBe('dry-run');
+    expect(result.goal).toBe('Fill contact form');
     await browser.close();
   });
 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 76c09cc..a4c447f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -104,7 +104,14 @@ importers:
         version: 2.1.9(@types/node@24.13.2)(happy-dom@20.10.6)(lightningcss@1.32.0)(terser@5.48.0)
 
   packages/agent-runtime:
+    dependencies:
+      '@tronbrowser/browser-core':
+        specifier: workspace:*
+        version: link:../browser-core
     devDependencies:
+      happy-dom:
+        specifier: ^20.10.6
+        version: 20.10.6
       typescript:
         specifier: ^5.6.3
         version: 5.9.3
@@ -171,6 +178,9 @@ importers:
 
   packages/sdk:
     dependencies:
+      '@tronbrowser/agent-runtime':
+        specifier: workspace:*
+        version: link:../agent-runtime
       '@tronbrowser/browser-core':
         specifier: workspace:*
         version: link:../browser-core