sel2pw 0.1.1__tar.gz

sel2pw-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shan Konduru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sel2pw-0.1.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: sel2pw
+Version: 0.1.1
+Summary: Selenium Java -> Python Playwright migration agent (CLI, MCP server, LLM-agnostic agent)
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == "openai"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: anthropic>=1.0; extra == "all"
+Requires-Dist: openai>=1.40; extra == "all"
+Requires-Dist: mcp>=2.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: anthropic>=1.0; extra == "dev"
+Requires-Dist: openai>=1.40; extra == "dev"
+Requires-Dist: mcp>=2.0; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# sel2pw — Selenium Java → Python Playwright migration agent
+
+[![Tests](https://github.com/ShanKonduru/selenium2playwright/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ShanKonduru/selenium2playwright/actions/workflows/tests.yml)
+
+Implements the agent described in
+[`selenium_java_to_playwright_migration_agent_system_prompt.md`](selenium_java_to_playwright_migration_agent_system_prompt.md)
+three ways, all on one shared core:
+
+| Surface | Command | Who does the reasoning |
+|---|---|---|
+| CLI | `sel2pw inventory / migrate / validate` | Built-in agent + any LLM provider |
+| MCP server | `sel2pw mcp` (or `sel2pw-mcp`) | The MCP host's LLM (Claude Code/Desktop, Copilot, Cursor…), or the built-in agent via `run_migration_agent` |
+| Library | `MigrationAgent(get_provider(...), Workspace.create(...)).run()` | Any `LLMProvider` |
+
+## Architecture
+
+```
+src/sel2pw/
+  workspace.py   sandbox: named roots (source=ro, target=rw, --reference=ro), path-escape checks, secret redaction
+  inventory.py   deterministic Java scan: tests (IDs "Class#method"), lifecycle hooks, page objects,
+                 dependencies, locators, data-provider rows, constructs to flag (waits, frames, alerts, JS, ...)
+  validate.py    compile (in-process), pytest --collect-only, pytest run (opt-in only)
+  ledger.py      structured mappings + issues recorded by the agent
+  gates.py       deterministic acceptance gates
+  reports.py     code-generated migration_map.md / migration_validation.md
+  manifest.py    run fingerprint + manifest under <target>/.sel2pw/runs/
+  tools.py       ONE tool registry + input validation, used by both the agent and the MCP server
+  agent.py       provider-agnostic loop (append-only history, gate-driven repair rounds, finalize)
+  llm/           base.py (neutral messages) + anthropic/openai adapters + registry + cache.py (record/replay)
+  prompts/       system_prompt.md (extracted from the spec) + static TOOL LAYER appendix
+  cli.py, mcp_server.py
+```
+
+The spec says *"prompt text alone is not a security boundary"*, so the tool layer enforces it:
+the source root is never writable; no path can leave its root; secrets are redacted before reaching any LLM;
+overwriting a target file that existed before the run is recorded and reported; browser execution
+(`run_check kind=run`) is refused unless the operator passes `--allow-browser-tests`.
+There is no generic shell tool.
+
+## Install
+
+```bash
+pip install -e ".[all]"        # or .[anthropic] / .[openai] / .[mcp]; .[dev] adds pytest
+```
+
+## CLI
+
+```bash
+# Deterministic inventory (no LLM, free)
+sel2pw inventory path/to/selenium-project --out inventory.md
+
+# Full migration with the built-in agent
+sel2pw migrate --source path/to/selenium-project --target path/to/innoharmony-repo \
+    --task "Migrate LoginTest and its page objects" --scope "LoginTest#*"
+
+# Static checks on migrated code (add --collect for pytest --collect-only)
+sel2pw validate path/to/innoharmony-repo --collect --python path/to/repo/.venv/Scripts/python
+```
+
+Useful `migrate` flags: `--reference innoharmony=path/to/framework` (extra read-only root),
+`--allow-browser-tests` (approved non-prod env only), `--python` (target repo's interpreter for pytest),
+`--scope`, `--max-repairs`, `--gate-collect`, `--report-dir`, `--cache`, `--max-turns`, `--system-prompt FILE`.
+Exit code is 0 only when the acceptance gates pass.
+
+## Determinism
+
+LLM output can't be made bit-for-bit deterministic. Claude Opus 5.5 rejects `temperature`, and OpenAI's `seed`
+is only best effort. sel2pw makes every *outcome* deterministic and every *run* reproducible:
+
+| Layer | Mechanism |
+|---|---|
+| **What counts as "done"** | Deterministic acceptance gates: `scope_coverage` (every in-scope test mapped), `mapping_integrity` (target file + symbol exist, blocked/excluded have reasons), `assertion_parity`, `parametrize_parity` (data-provider rows = `parametrize` cases), `disabled_preserved` (stays skipped), `compile`, `lint` (no unjustified sleeps/`networkidle`, no secrets or redacted placeholders), optional `collect`. Failures are sent back to the model for up to `--max-repairs` rounds, and the run fails if they persist. |
+| **Reports** | The agent records structured data (`record_mapping`, `record_issue`). It cannot write `migration_map.md` or `migration_validation.md`. Code renders both, with no timestamps, so identical inputs give byte-identical reports. Text the model wrote is shown in labelled "agent" columns or sections. |
+| **Reproducing a run** | Record/replay cache (`--cache auto` by default) in `<target>/.sel2pw/cache`. It is keyed by a SHA-256 of the provider settings, system prompt, tool schemas and the whole conversation, including tool results. Re-running with the same inputs and the same starting target replays the run exactly without calling the model. `--cache replay` makes any deviation an error, which suits CI. `--cache off` forces a fresh attempt. Tool output is normalized (sorted listings, pytest timings stripped) so keys stay stable. |
+| **Traceability** | Every run writes `<target>/.sel2pw/runs/<run_id>/`: `manifest.json` (model + settings, prompt/tools/task/source-tree/inventory hashes, target tree hash before/after, cache hits, usage, SDK versions), `gates.json`, `ledger.json`, `events.jsonl`. The stable part of the fingerprint is also in the validation report. |
+
+Escape hatches the gates recognise (all appear in reports for reviewers): a `justification` on a mapping
+(intentional assertion, case or skip difference), and line comments `# sel2pw: allow-sleep: <reason>`,
+`# sel2pw: allow-networkidle: <reason>`, `# sel2pw: allow-secret` (test data, not credentials).
+
+Add `.sel2pw/` to the target's `.gitignore`, or commit `.sel2pw/cache` if you want others to be able to replay your runs.
+
+### LLM providers (`sel2pw providers`)
+
+| `--provider` | Notes |
+|---|---|
+| `anthropic` (default) | Default model `claude-opus-5-5`. Auth: `ANTHROPIC_API_KEY` or `ant auth login`. |
+| `openai` | `OPENAI_API_KEY`, `--model` required |
+| `azure-openai` | `AZURE_OPENAI_BASE_URL` (v1 endpoint) + `AZURE_OPENAI_API_KEY`; `--model` = deployment |
+| `gemini` | `GEMINI_API_KEY`, OpenAI-compatible endpoint, `--model` required |
+| `ollama` | Local, `OLLAMA_BASE_URL` (default `http://localhost:11434/v1`); use a tool-capable model |
+| `openai-compatible` | vLLM, LM Studio, OpenRouter, LiteLLM… via `SEL2PW_BASE_URL` / `SEL2PW_API_KEY` |
+| `my_pkg.module:MyProvider` | Plugin: any `sel2pw.llm.base.LLMProvider` subclass |
+
+Defaults can come from env: `SEL2PW_PROVIDER`, `SEL2PW_MODEL`, `SEL2PW_EFFORT`.
+
+Anthropic adapter specifics: streaming with `eager_input_streaming` tools (whole-file writes stream as they are
+generated; inputs are re-validated before running), adaptive thinking with `--effort` (default `high`),
+automatic prompt caching, and **server-side refusal fallbacks enabled by default** (`fallbacks="default"`).
+Pass `--no-fallbacks` to turn them off; you must do that on Bedrock/Vertex/Foundry gateways, where the parameter is rejected.
+
+### Adding a provider
+
+```python
+from sel2pw.llm.base import LLMProvider, AssistantTurn, ToolCall
+
+class MyProvider(LLMProvider):
+    name = "mine"
+    def __init__(self, model=None, **kw):
+        super().__init__(model or "my-model")
+    def complete(self, system, messages, tools) -> AssistantTurn:
+        ...  # convert UserMessage / AssistantTurn(raw) / ToolResultsMessage to your API, call it,
+             # return AssistantTurn(text, [ToolCall(id, name, args)], stop_reason, raw=<native turn>)
+```
+
+```bash
+sel2pw migrate --provider my_pkg.providers:MyProvider ...
+```
+
+## MCP server
+
+Tools: `java_inventory`, `list_files`, `read_file`, `search`, `write_file`, `edit_file`, `run_check`,
+`record_mapping`, `record_issue`, `check_acceptance`, `finalize_migration` (gates + generated reports + run manifest),
+`run_migration_agent` (hide with `--no-agent-tool`). Prompt: `migrate_selenium_to_playwright`.
+Resource: `sel2pw://system-prompt`. The roots, `--scope` and gate options are fixed at server start, so a host
+can't widen the scope. Host-driven runs get the same gates and generated reports through `finalize_migration`.
+
+**Claude Code**
+
+```bash
+claude mcp add sel2pw -- sel2pw mcp --source C:/work/selenium-tests --target C:/work/innoharmony-tests
+```
+
+**VS Code / Cursor / Claude Desktop** (`mcp.json` / `claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "sel2pw": {
+      "command": "C:/myprojects/selenium2playwright/.venv/Scripts/sel2pw.exe",
+      "args": ["mcp", "--source", "C:/work/selenium-tests", "--target", "C:/work/innoharmony-tests"]
+    }
+  }
+}
+```
+
+HTTP transport: `sel2pw mcp ... --transport streamable-http`.
+
+## Tests
+
+```bash
+pytest -q
+```
+
+No test calls a real LLM. The provider adapters are tested against fake clients, and the MCP tests run the
+server in-process.

sel2pw-0.1.1/README.md

@@ -0,0 +1,156 @@
+# sel2pw — Selenium Java → Python Playwright migration agent
+
+[![Tests](https://github.com/ShanKonduru/selenium2playwright/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ShanKonduru/selenium2playwright/actions/workflows/tests.yml)
+
+Implements the agent described in
+[`selenium_java_to_playwright_migration_agent_system_prompt.md`](selenium_java_to_playwright_migration_agent_system_prompt.md)
+three ways, all on one shared core:
+
+| Surface | Command | Who does the reasoning |
+|---|---|---|
+| CLI | `sel2pw inventory / migrate / validate` | Built-in agent + any LLM provider |
+| MCP server | `sel2pw mcp` (or `sel2pw-mcp`) | The MCP host's LLM (Claude Code/Desktop, Copilot, Cursor…), or the built-in agent via `run_migration_agent` |
+| Library | `MigrationAgent(get_provider(...), Workspace.create(...)).run()` | Any `LLMProvider` |
+
+## Architecture
+
+```
+src/sel2pw/
+  workspace.py   sandbox: named roots (source=ro, target=rw, --reference=ro), path-escape checks, secret redaction
+  inventory.py   deterministic Java scan: tests (IDs "Class#method"), lifecycle hooks, page objects,
+                 dependencies, locators, data-provider rows, constructs to flag (waits, frames, alerts, JS, ...)
+  validate.py    compile (in-process), pytest --collect-only, pytest run (opt-in only)
+  ledger.py      structured mappings + issues recorded by the agent
+  gates.py       deterministic acceptance gates
+  reports.py     code-generated migration_map.md / migration_validation.md
+  manifest.py    run fingerprint + manifest under <target>/.sel2pw/runs/
+  tools.py       ONE tool registry + input validation, used by both the agent and the MCP server
+  agent.py       provider-agnostic loop (append-only history, gate-driven repair rounds, finalize)
+  llm/           base.py (neutral messages) + anthropic/openai adapters + registry + cache.py (record/replay)
+  prompts/       system_prompt.md (extracted from the spec) + static TOOL LAYER appendix
+  cli.py, mcp_server.py
+```
+
+The spec says *"prompt text alone is not a security boundary"*, so the tool layer enforces it:
+the source root is never writable; no path can leave its root; secrets are redacted before reaching any LLM;
+overwriting a target file that existed before the run is recorded and reported; browser execution
+(`run_check kind=run`) is refused unless the operator passes `--allow-browser-tests`.
+There is no generic shell tool.
+
+## Install
+
+```bash
+pip install -e ".[all]"        # or .[anthropic] / .[openai] / .[mcp]; .[dev] adds pytest
+```
+
+## CLI
+
+```bash
+# Deterministic inventory (no LLM, free)
+sel2pw inventory path/to/selenium-project --out inventory.md
+
+# Full migration with the built-in agent
+sel2pw migrate --source path/to/selenium-project --target path/to/innoharmony-repo \
+    --task "Migrate LoginTest and its page objects" --scope "LoginTest#*"
+
+# Static checks on migrated code (add --collect for pytest --collect-only)
+sel2pw validate path/to/innoharmony-repo --collect --python path/to/repo/.venv/Scripts/python
+```
+
+Useful `migrate` flags: `--reference innoharmony=path/to/framework` (extra read-only root),
+`--allow-browser-tests` (approved non-prod env only), `--python` (target repo's interpreter for pytest),
+`--scope`, `--max-repairs`, `--gate-collect`, `--report-dir`, `--cache`, `--max-turns`, `--system-prompt FILE`.
+Exit code is 0 only when the acceptance gates pass.
+
+## Determinism
+
+LLM output can't be made bit-for-bit deterministic. Claude Opus 5.5 rejects `temperature`, and OpenAI's `seed`
+is only best effort. sel2pw makes every *outcome* deterministic and every *run* reproducible:
+
+| Layer | Mechanism |
+|---|---|
+| **What counts as "done"** | Deterministic acceptance gates: `scope_coverage` (every in-scope test mapped), `mapping_integrity` (target file + symbol exist, blocked/excluded have reasons), `assertion_parity`, `parametrize_parity` (data-provider rows = `parametrize` cases), `disabled_preserved` (stays skipped), `compile`, `lint` (no unjustified sleeps/`networkidle`, no secrets or redacted placeholders), optional `collect`. Failures are sent back to the model for up to `--max-repairs` rounds, and the run fails if they persist. |
+| **Reports** | The agent records structured data (`record_mapping`, `record_issue`). It cannot write `migration_map.md` or `migration_validation.md`. Code renders both, with no timestamps, so identical inputs give byte-identical reports. Text the model wrote is shown in labelled "agent" columns or sections. |
+| **Reproducing a run** | Record/replay cache (`--cache auto` by default) in `<target>/.sel2pw/cache`. It is keyed by a SHA-256 of the provider settings, system prompt, tool schemas and the whole conversation, including tool results. Re-running with the same inputs and the same starting target replays the run exactly without calling the model. `--cache replay` makes any deviation an error, which suits CI. `--cache off` forces a fresh attempt. Tool output is normalized (sorted listings, pytest timings stripped) so keys stay stable. |
+| **Traceability** | Every run writes `<target>/.sel2pw/runs/<run_id>/`: `manifest.json` (model + settings, prompt/tools/task/source-tree/inventory hashes, target tree hash before/after, cache hits, usage, SDK versions), `gates.json`, `ledger.json`, `events.jsonl`. The stable part of the fingerprint is also in the validation report. |
+
+Escape hatches the gates recognise (all appear in reports for reviewers): a `justification` on a mapping
+(intentional assertion, case or skip difference), and line comments `# sel2pw: allow-sleep: <reason>`,
+`# sel2pw: allow-networkidle: <reason>`, `# sel2pw: allow-secret` (test data, not credentials).
+
+Add `.sel2pw/` to the target's `.gitignore`, or commit `.sel2pw/cache` if you want others to be able to replay your runs.
+
+### LLM providers (`sel2pw providers`)
+
+| `--provider` | Notes |
+|---|---|
+| `anthropic` (default) | Default model `claude-opus-5-5`. Auth: `ANTHROPIC_API_KEY` or `ant auth login`. |
+| `openai` | `OPENAI_API_KEY`, `--model` required |
+| `azure-openai` | `AZURE_OPENAI_BASE_URL` (v1 endpoint) + `AZURE_OPENAI_API_KEY`; `--model` = deployment |
+| `gemini` | `GEMINI_API_KEY`, OpenAI-compatible endpoint, `--model` required |
+| `ollama` | Local, `OLLAMA_BASE_URL` (default `http://localhost:11434/v1`); use a tool-capable model |
+| `openai-compatible` | vLLM, LM Studio, OpenRouter, LiteLLM… via `SEL2PW_BASE_URL` / `SEL2PW_API_KEY` |
+| `my_pkg.module:MyProvider` | Plugin: any `sel2pw.llm.base.LLMProvider` subclass |
+
+Defaults can come from env: `SEL2PW_PROVIDER`, `SEL2PW_MODEL`, `SEL2PW_EFFORT`.
+
+Anthropic adapter specifics: streaming with `eager_input_streaming` tools (whole-file writes stream as they are
+generated; inputs are re-validated before running), adaptive thinking with `--effort` (default `high`),
+automatic prompt caching, and **server-side refusal fallbacks enabled by default** (`fallbacks="default"`).
+Pass `--no-fallbacks` to turn them off; you must do that on Bedrock/Vertex/Foundry gateways, where the parameter is rejected.
+
+### Adding a provider
+
+```python
+from sel2pw.llm.base import LLMProvider, AssistantTurn, ToolCall
+
+class MyProvider(LLMProvider):
+    name = "mine"
+    def __init__(self, model=None, **kw):
+        super().__init__(model or "my-model")
+    def complete(self, system, messages, tools) -> AssistantTurn:
+        ...  # convert UserMessage / AssistantTurn(raw) / ToolResultsMessage to your API, call it,
+             # return AssistantTurn(text, [ToolCall(id, name, args)], stop_reason, raw=<native turn>)
+```
+
+```bash
+sel2pw migrate --provider my_pkg.providers:MyProvider ...
+```
+
+## MCP server
+
+Tools: `java_inventory`, `list_files`, `read_file`, `search`, `write_file`, `edit_file`, `run_check`,
+`record_mapping`, `record_issue`, `check_acceptance`, `finalize_migration` (gates + generated reports + run manifest),
+`run_migration_agent` (hide with `--no-agent-tool`). Prompt: `migrate_selenium_to_playwright`.
+Resource: `sel2pw://system-prompt`. The roots, `--scope` and gate options are fixed at server start, so a host
+can't widen the scope. Host-driven runs get the same gates and generated reports through `finalize_migration`.
+
+**Claude Code**
+
+```bash
+claude mcp add sel2pw -- sel2pw mcp --source C:/work/selenium-tests --target C:/work/innoharmony-tests
+```
+
+**VS Code / Cursor / Claude Desktop** (`mcp.json` / `claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "sel2pw": {
+      "command": "C:/myprojects/selenium2playwright/.venv/Scripts/sel2pw.exe",
+      "args": ["mcp", "--source", "C:/work/selenium-tests", "--target", "C:/work/innoharmony-tests"]
+    }
+  }
+}
+```
+
+HTTP transport: `sel2pw mcp ... --transport streamable-http`.
+
+## Tests
+
+```bash
+pytest -q
+```
+
+No test calls a real LLM. The provider adapters are tested against fake clients, and the MCP tests run the
+server in-process.

sel2pw-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sel2pw"
+version = "0.1.1"
+description = "Selenium Java -> Python Playwright migration agent (CLI, MCP server, LLM-agnostic agent)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=1.0"]
+openai = ["openai>=1.40"]
+mcp = ["mcp>=2.0"]
+all = ["anthropic>=1.0", "openai>=1.40", "mcp>=2.0"]
+dev = ["anthropic>=1.0", "openai>=1.40", "mcp>=2.0", "pytest>=8"]
+
+[project.scripts]
+sel2pw = "sel2pw.cli:main"
+sel2pw-mcp = "sel2pw.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sel2pw = ["prompts/*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+norecursedirs = ["fixtures"]

sel2pw-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sel2pw-0.1.1/src/sel2pw/__init__.py

@@ -0,0 +1,3 @@
+"""Selenium Java -> Python Playwright migration agent."""
+
+__version__ = "0.1.1"

sel2pw-0.1.1/src/sel2pw/agent.py

@@ -0,0 +1,230 @@
+"""Provider-agnostic migration agent loop.
+
+The model works through the tools; when it stops, the harness runs the
+deterministic acceptance gates. Failures go back to the model as a repair
+request (up to ``max_repairs`` rounds). Reports and the run manifest are then
+generated by code, never by the model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .gates import GateReport
+from .llm.base import (
+    AssistantTurn,
+    LLMProvider,
+    Message,
+    ToolDef,
+    ToolResult,
+    ToolResultsMessage,
+    UserMessage,
+)
+from .manifest import RunRecorder, sha256_json, sha256_text
+from .prompts import system_prompt, task_message
+from .tools import ToolBox
+from .workspace import Workspace
+
+EventHandler = Callable[[str, dict], None]
+
+MAX_TOKEN_CONTINUATIONS = 3
+
+
+@dataclass
+class AgentResult:
+    final_text: str
+    stop: str  # accepted | gates_failed | refusal | max_turns | max_tokens
+    turns: int
+    usage: dict[str, int] = field(default_factory=dict)
+    files_written: list[str] = field(default_factory=list)
+    modified_existing: list[str] = field(default_factory=list)
+    checks_run: list[str] = field(default_factory=list)
+    detail: str | None = None
+    gates: GateReport | None = None
+    reports: list[str] = field(default_factory=list)
+    repairs: int = 0
+    run_dir: str | None = None
+    fingerprint: dict = field(default_factory=dict)
+
+    @property
+    def accepted(self) -> bool:
+        return self.stop == "accepted"
+
+
+class MigrationAgent:
+    def __init__(
+        self,
+        provider: LLMProvider,
+        workspace: Workspace,
+        *,
+        allow_browser_tests: bool = False,
+        python: str | None = None,
+        max_turns: int = 80,
+        max_repairs: int = 3,
+        scope: list[str] | None = None,
+        gate_collect: bool = False,
+        report_dir: str = "",
+        system_prompt_path: str | None = None,
+        record_run: bool = True,
+        on_event: EventHandler | None = None,
+    ):
+        self.provider = provider
+        self.ws = workspace
+        self.allow_browser_tests = allow_browser_tests
+        self.toolbox = ToolBox(workspace, allow_browser_tests=allow_browser_tests, python=python,
+                               scope=scope, gate_collect=gate_collect, report_dir=report_dir)
+        self.max_turns = max_turns
+        self.max_repairs = max_repairs
+        self.system = system_prompt(system_prompt_path)
+        self.recorder = RunRecorder(workspace.root("target").path) if record_run else None
+        user_handler = on_event or (lambda kind, data: None)
+
+        def emit(kind: str, data: dict) -> None:
+            if self.recorder:
+                self.recorder.event(kind, data)
+            user_handler(kind, data)
+
+        self.on_event = emit
+        self.tools = [ToolDef(s.name, s.description, s.input_schema) for s in self.toolbox.specs.values()]
+
+    # -- fingerprint ---------------------------------------------------
+    def fingerprint(self, task_text: str) -> dict:
+        from .manifest import tree_hash
+
+        return {
+            **{f"llm.{k}": v for k, v in self.provider.fingerprint().items()},
+            "system_prompt_sha256": sha256_text(self.system),
+            "tools_sha256": sha256_json([[t.name, t.description, t.input_schema] for t in self.tools]),
+            "task_sha256": sha256_text(task_text),
+            "source_tree_sha256": tree_hash(self.ws.root("source").path),
+            "inventory_sha256": sha256_text(self.toolbox.inventory.to_json()),
+            "scope": ",".join(self.toolbox.scope or ["*"]),
+            "gate_collect": self.toolbox.gate_collect,
+            "browser_tests_allowed": self.allow_browser_tests,
+        }
+
+    # -- loop ----------------------------------------------------------
+    def run(self, task: str | None = None) -> AgentResult:
+        from .manifest import tree_hash
+
+        first = task_message(task, self.ws.describe(), self.allow_browser_tests, self.toolbox.scope)
+        fingerprint = self.fingerprint(first)
+        target_before = tree_hash(self.ws.root("target").path)
+        messages: list[Message] = [UserMessage(first)]
+        usage: dict[str, int] = {}
+        continuations = repairs = 0
+        last: AssistantTurn | None = None
+        stop, detail, gates = "max_turns", f"stopped after {self.max_turns} turns", None
+        turn = 0
+
+        for turn in range(1, self.max_turns + 1):
+            last = self.provider.complete(self.system, messages, self.tools)
+            messages.append(last)
+            for k, v in last.usage.items():
+                usage[k] = usage.get(k, 0) + v
+            self.on_event("assistant", {"turn": turn, "text": last.text, "stop": last.stop_reason, "tool_calls": len(last.tool_calls)})
+
+            if last.stop_reason == "refusal":
+                stop, detail = "refusal", last.detail
+                break
+            if last.stop_reason == "pause":
+                continue  # server paused a long turn; re-send to resume
+
+            if not last.tool_calls:
+                if last.stop_reason == "max_tokens" and continuations < MAX_TOKEN_CONTINUATIONS:
+                    continuations += 1
+                    messages.append(UserMessage("Your previous reply was cut off at the output limit. Continue from where you stopped."))
+                    continue
+                if last.stop_reason == "max_tokens":
+                    stop, detail = "max_tokens", "output limit reached repeatedly"
+                    break
+                gates = self.toolbox.evaluate_gates()
+                self.on_event("gates", {"turn": turn, "passed": gates.passed,
+                                        "failed": [r.name for r in gates.results if r.status == "fail"]})
+                if gates.passed:
+                    stop, detail = "accepted", None
+                    break
+                if repairs >= self.max_repairs:
+                    stop, detail = "gates_failed", f"gates still failing after {repairs} repair round(s)"
+                    break
+                repairs += 1
+                messages.append(UserMessage(gates.feedback()))
+                continue
+
+            messages.append(ToolResultsMessage(self._run_tools(turn, last)))
+
+        if gates is None or stop not in ("accepted", "gates_failed"):
+            gates = self.toolbox.evaluate_gates()
+        reports = self.toolbox.write_reports(gates, fingerprint, last.text if last else "")
+        result = AgentResult(
+            final_text=last.text if last else "",
+            stop=stop,
+            turns=turn,
+            usage=usage,
+            files_written=list(self.ws.written),
+            modified_existing=list(self.ws.modified_existing),
+            checks_run=list(self.toolbox.checks_run),
+            detail=detail,
+            gates=gates,
+            reports=reports,
+            repairs=repairs,
+            fingerprint=fingerprint,
+        )
+        if self.recorder:
+            self._write_manifest(result, target_before)
+        return result
+
+    def _run_tools(self, turn: int, last: AssistantTurn) -> list[ToolResult]:
+        results = []
+        for call in last.tool_calls:
+            if last.stop_reason == "max_tokens":
+                # A truncated tool input can still parse as a valid partial object - never run it.
+                output, is_error = (
+                    "Not executed: your reply hit the output limit, so this tool input may be truncated. "
+                    "Re-issue the call; split large files into smaller write_file/edit_file calls.",
+                    True,
+                )
+            elif call.parse_error:
+                output, is_error = f"Not executed: {call.parse_error}. Re-issue the call with valid JSON arguments.", True
+            else:
+                self.on_event("tool_call", {"turn": turn, "name": call.name, "arguments": _summarize_args(call.arguments)})
+                output, is_error = self.toolbox.call(call.name, call.arguments)
+                self.on_event("tool_result", {"turn": turn, "name": call.name, "is_error": is_error, "preview": output[:200]})
+            results.append(ToolResult(call.id, call.name, output, is_error))
+        return results
+
+    def _write_manifest(self, result: AgentResult, target_before: str) -> None:
+        from .manifest import tree_hash
+
+        assert self.recorder is not None
+        cache = {}
+        if hasattr(self.provider, "hits"):
+            cache = {"mode": getattr(self.provider, "mode", None), "hits": self.provider.hits, "misses": self.provider.misses}
+        self.recorder.write("ledger.json", self.toolbox.ledger.to_dict())
+        self.recorder.write("gates.json", result.gates.to_dict() if result.gates else {})
+        self.recorder.manifest(result.fingerprint, {
+            "stop": result.stop,
+            "detail": result.detail,
+            "turns": result.turns,
+            "repairs": result.repairs,
+            "usage": result.usage,
+            "cache": cache,
+            "files_written": result.files_written,
+            "modified_existing": result.modified_existing,
+            "reports": result.reports,
+            "checks_run": result.checks_run,
+            "target_tree_sha256_before": target_before,
+            "target_tree_sha256_after": tree_hash(self.ws.root("target").path),
+        })
+        result.run_dir = str(self.recorder.run_dir)
+
+
+def _summarize_args(args: object) -> dict:
+    if not isinstance(args, dict):
+        return {"_": str(args)[:80]}
+    out = {}
+    for k, v in args.items():
+        s = v if isinstance(v, (int, bool)) else str(v)
+        out[k] = s if not isinstance(s, str) or len(s) <= 80 else f"<{len(s)} chars>"
+    return out