[codex] Maintenance quickstart and issue hygiene

README.md

@@ -14,7 +14,7 @@
 ![Python](https://img.shields.io/badge/python-3.11%2B-3776ab)
 ![Node](https://img.shields.io/badge/node-20%2B-3c873a)
 
-[Architecture](docs/architecture.md) | [Event Schema](docs/event-schema.md) | [Workflow Graph](docs/workflow-graph.md) | [Evaluation](docs/evaluation.md) | [Deployment](docs/deployment.md) | [DeepSeek](docs/deepseek.md) | [Roadmap](PLAN.md)
+[Architecture](docs/architecture.md) | [Event Schema](docs/event-schema.md) | [Workflow Graph](docs/workflow-graph.md) | [Evaluation](docs/evaluation.md) | [Deployment](docs/deployment.md) | [DeepSeek](docs/deepseek.md) | [Roadmap](docs/dev/PLAN.md)
 
 </div>
 
@@ -39,12 +39,12 @@ Open:
 http://localhost:3000
 ```
 
-Prefer the terminal? Run the whole pipeline:
+Prefer the terminal? Run the calendar demo pipeline:
 
 ```bash
 cd apps/api
 pip install -e ".[dev]"
-python -m app.scripts.demo
+python -m app.scripts.demo calendar-demo
 ```
 
 Optional full-stack Docker path (requires Docker Desktop or another Docker engine running):

apps/api/app/scripts/demo.py

@@ -1,8 +1,9 @@
-"""Run the full AgentReplay pipeline against the seeded checkout workflow and
+"""Run the full AgentReplay pipeline against a seeded demo workflow and
 print a readable report.
 
 Usage:
     python -m app.scripts.demo               # divergent agent (default)
+    python -m app.scripts.demo calendar-demo # calendar workflow, divergent agent
     python -m app.scripts.demo scripted      # always-correct baseline
     python -m app.scripts.demo llm           # DeepSeek v4 Pro (needs DEEPSEEK_API_KEY)
 """
@@ -29,18 +30,31 @@ def _fmtd(c: dict) -> str:
 
 
 def main() -> None:
-    graph = state.seed()
+    state.seed()
+    workflow_id = state.WORKFLOW_ID
+    driver = os.getenv("DRIVER", "divergent")
+    args = sys.argv[1:]
+    if args:
+        if args[0] in state.RECORDINGS:
+            workflow_id = args[0]
+            if len(args) > 1:
+                driver = args[1]
+        else:
+            driver = args[0]
+
+    graph = state.store.get_graph(workflow_id)
+    if graph is None:
+        raise ValueError(f"unknown workflow: {workflow_id}")
     human = graph.human_commands()
-    driver = sys.argv[1] if len(sys.argv) > 1 else os.getenv("DRIVER", "divergent")
-    run = run_agent(state.store, state.WORKFLOW_ID, driver, goal="complete a checkout")
+    run = run_agent(state.store, workflow_id, driver, goal=state.goal_for_workflow(workflow_id))
     m, s = run["metrics"], run["summary"]
     div = m["divergence_step"]
 
     bar = "=" * 72
     print(bar)
     print("AgentReplay - record -> compile -> run -> compare -> explain -> export")
     print(bar)
-    print(f"Workflow: {state.WORKFLOW_ID}   nodes={len(graph.nodes)}  human_actions={len(human)}")
+    print(f"Workflow: {workflow_id}   nodes={len(graph.nodes)}  human_actions={len(human)}")
     print(f"Driver: {driver}   DeepSeek enabled: {run.get('llmEnabled', False)}")
 
     print("\nHuman path:")

apps/api/tests/test_demo_script.py

@@ -0,0 +1,13 @@
+import sys
+
+from app.scripts import demo
+
+
+def test_demo_script_runs_calendar_workflow(monkeypatch, capsys):
+    monkeypatch.setattr(sys, "argv", ["demo", "calendar-demo"])
+
+    demo.main()
+
+    out = capsys.readouterr().out
+    assert "Workflow: calendar-demo" in out
+    assert "create a calendar event" in out

artifacts/maintenance-20260702-api-pip-install.log

@@ -0,0 +1,69 @@
+Obtaining file:///C:/AgentReplay/apps/api
+  Installing build dependencies: started
+  Installing build dependencies: finished with status 'done'
+  Checking if build backend supports build_editable: started
+  Checking if build backend supports build_editable: finished with status 'done'
+  Getting requirements to build editable: started
+  Getting requirements to build editable: finished with status 'done'
+  Preparing editable metadata (pyproject.toml): started
+  Preparing editable metadata (pyproject.toml): finished with status 'done'
+Requirement already satisfied: fastapi>=0.110 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (0.138.0)
+Requirement already satisfied: uvicorn>=0.29 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (0.49.0)
+Requirement already satisfied: pydantic>=2.6 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (2.12.4)
+Requirement already satisfied: psycopg>=3.1 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from psycopg[binary]>=3.1->agentreplay-api==0.1.0) (3.3.4)
+Requirement already satisfied: redis>=5.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (8.0.0)
+Requirement already satisfied: playwright>=1.43 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (1.60.0)
+Requirement already satisfied: openai>=1.40 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (2.7.1)
+Requirement already satisfied: pytest>=8 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (8.4.2)
+Requirement already satisfied: ruff>=0.4 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (0.15.20)
+Requirement already satisfied: mypy>=1.9 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (2.1.0)
+Requirement already satisfied: httpx>=0.27 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from agentreplay-api==0.1.0) (0.28.1)
+Requirement already satisfied: starlette>=0.46.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from fastapi>=0.110->agentreplay-api==0.1.0) (1.3.1)
+Requirement already satisfied: typing-extensions>=4.8.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from fastapi>=0.110->agentreplay-api==0.1.0) (4.15.0)
+Requirement already satisfied: typing-inspection>=0.4.2 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from fastapi>=0.110->agentreplay-api==0.1.0) (0.4.2)
+Requirement already satisfied: annotated-doc>=0.0.2 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from fastapi>=0.110->agentreplay-api==0.1.0) (0.0.4)
+Requirement already satisfied: anyio in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from httpx>=0.27->agentreplay-api==0.1.0) (4.11.0)
+Requirement already satisfied: certifi in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from httpx>=0.27->agentreplay-api==0.1.0) (2025.10.5)
+Requirement already satisfied: httpcore==1.* in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from httpx>=0.27->agentreplay-api==0.1.0) (1.0.9)
+Requirement already satisfied: idna in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from httpx>=0.27->agentreplay-api==0.1.0) (3.11)
+Requirement already satisfied: h11>=0.16 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from httpcore==1.*->httpx>=0.27->agentreplay-api==0.1.0) (0.16.0)
+Requirement already satisfied: mypy_extensions>=1.0.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from mypy>=1.9->agentreplay-api==0.1.0) (1.1.0)
+Requirement already satisfied: pathspec>=1.0.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from mypy>=1.9->agentreplay-api==0.1.0) (1.1.1)
+Requirement already satisfied: librt>=0.11.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from mypy>=1.9->agentreplay-api==0.1.0) (0.11.0)
+Requirement already satisfied: ast-serialize<1.0.0,>=0.3.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from mypy>=1.9->agentreplay-api==0.1.0) (0.5.0)
+Requirement already satisfied: distro<2,>=1.7.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from openai>=1.40->agentreplay-api==0.1.0) (1.9.0)
+Requirement already satisfied: jiter<1,>=0.10.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from openai>=1.40->agentreplay-api==0.1.0) (0.11.1)
+Requirement already satisfied: sniffio in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from openai>=1.40->agentreplay-api==0.1.0) (1.3.1)
+Requirement already satisfied: tqdm>4 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from openai>=1.40->agentreplay-api==0.1.0) (4.67.1)
+Requirement already satisfied: annotated-types>=0.6.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pydantic>=2.6->agentreplay-api==0.1.0) (0.7.0)
+Requirement already satisfied: pydantic-core==2.41.5 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pydantic>=2.6->agentreplay-api==0.1.0) (2.41.5)
+Requirement already satisfied: pyee<14,>=13 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from playwright>=1.43->agentreplay-api==0.1.0) (13.0.1)
+Requirement already satisfied: greenlet<4.0.0,>=3.1.1 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from playwright>=1.43->agentreplay-api==0.1.0) (3.5.1)
+Requirement already satisfied: tzdata in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from psycopg>=3.1->psycopg[binary]>=3.1->agentreplay-api==0.1.0) (2025.2)
+Requirement already satisfied: psycopg-binary==3.3.4 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from psycopg[binary]>=3.1->agentreplay-api==0.1.0) (3.3.4)
+Requirement already satisfied: colorama>=0.4 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pytest>=8->agentreplay-api==0.1.0) (0.4.6)
+Requirement already satisfied: iniconfig>=1 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pytest>=8->agentreplay-api==0.1.0) (2.3.0)
+Requirement already satisfied: packaging>=20 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pytest>=8->agentreplay-api==0.1.0) (25.0)
+Requirement already satisfied: pluggy<2,>=1.5 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pytest>=8->agentreplay-api==0.1.0) (1.6.0)
+Requirement already satisfied: pygments>=2.7.2 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from pytest>=8->agentreplay-api==0.1.0) (2.20.0)
+Requirement already satisfied: click>=7.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn>=0.29->uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (8.4.1)
+Requirement already satisfied: httptools>=0.8.0 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (0.8.0)
+Requirement already satisfied: python-dotenv>=0.13 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (1.2.2)
+Requirement already satisfied: pyyaml>=5.1 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (6.0.3)
+Requirement already satisfied: watchfiles>=0.20 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (1.2.0)
+Requirement already satisfied: websockets>=10.4 in c:\users\caesa\appdata\local\programs\python\python313\lib\site-packages (from uvicorn[standard]>=0.29->agentreplay-api==0.1.0) (15.0.1)
+Building wheels for collected packages: agentreplay-api
+  Building editable for agentreplay-api (pyproject.toml): started
+  Building editable for agentreplay-api (pyproject.toml): finished with status 'done'
+  Created wheel for agentreplay-api: filename=agentreplay_api-0.1.0-0.editable-py3-none-any.whl size=2968 sha256=71a7a479b930fc6800d40936bf4340b55ec927d3a08a2f6773f3bee8d87bc87e
+  Stored in directory: C:\Users\caesa\AppData\Local\Temp\pip-ephem-wheel-cache-tznxne4d\wheels\3f\35\e6\e3b941d34382cda945a510c2b9d24afab8e73e0f0a565fcf9a
+Successfully built agentreplay-api
+Installing collected packages: agentreplay-api
+  Attempting uninstall: agentreplay-api
+    Found existing installation: agentreplay-api 0.1.0
+    Uninstalling agentreplay-api-0.1.0:
+      Successfully uninstalled agentreplay-api-0.1.0
+Successfully installed agentreplay-api-0.1.0
+
+[notice] A new release of pip is available: 25.3 -> 26.1.2
+[notice] To update, run: python.exe -m pip install --upgrade pip

artifacts/maintenance-20260702-api-pytest-rerun.log

@@ -0,0 +1,30 @@
+C:\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\requests\__init__.py:113: RequestsDependencyWarning: urllib3 (2.5.0) or chardet (7.4.3)/charset_normalizer (3.4.4) doesn't match a supported version!
+  warnings.warn(
+============================= test session starts =============================
+platform win32 -- Python 3.13.5, pytest-8.4.2, pluggy-1.6.0
+rootdir: C:\AgentReplay\apps\api
+configfile: pyproject.toml
+plugins: anyio-4.11.0, langsmith-0.7.36, asyncio-1.4.0
+asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
+collected 43 items
+
+apps\api\tests\test_api.py ........                                      [ 18%]
+apps\api\tests\test_benchmark.py ....                                    [ 27%]
+apps\api\tests\test_compiler.py ....                                     [ 37%]
+apps\api\tests\test_deepseek.py .....                                    [ 48%]
+apps\api\tests\test_demo_script.py .                                     [ 51%]
+apps\api\tests\test_drivers.py ....                                      [ 60%]
+apps\api\tests\test_generator.py .                                       [ 62%]
+apps\api\tests\test_metrics.py .....                                     [ 74%]
+apps\api\tests\test_objects.py ...                                       [ 81%]
+apps\api\tests\test_pipeline.py ..                                       [ 86%]
+apps\api\tests\test_playwright.py ....                                   [ 95%]
+apps\api\tests\test_store.py .s                                          [100%]
+
+============================== warnings summary ===============================
+..\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\fastapi\testclient.py:1
+  C:\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\fastapi\testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================== 42 passed, 1 skipped, 1 warning in 1.14s ===================

artifacts/maintenance-20260702-api-pytest.log

@@ -0,0 +1,30 @@
+C:\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\requests\__init__.py:113: RequestsDependencyWarning: urllib3 (2.5.0) or chardet (7.4.3)/charset_normalizer (3.4.4) doesn't match a supported version!
+  warnings.warn(
+============================= test session starts =============================
+platform win32 -- Python 3.13.5, pytest-8.4.2, pluggy-1.6.0
+rootdir: C:\AgentReplay\apps\api
+configfile: pyproject.toml
+plugins: anyio-4.11.0, langsmith-0.7.36, asyncio-1.4.0
+asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
+collected 43 items
+
+apps\api\tests\test_api.py ........                                      [ 18%]
+apps\api\tests\test_benchmark.py ....                                    [ 27%]
+apps\api\tests\test_compiler.py ....                                     [ 37%]
+apps\api\tests\test_deepseek.py .....                                    [ 48%]
+apps\api\tests\test_demo_script.py .                                     [ 51%]
+apps\api\tests\test_drivers.py ....                                      [ 60%]
+apps\api\tests\test_generator.py .                                       [ 62%]
+apps\api\tests\test_metrics.py .....                                     [ 74%]
+apps\api\tests\test_objects.py ...                                       [ 81%]
+apps\api\tests\test_pipeline.py ..                                       [ 86%]
+apps\api\tests\test_playwright.py ....                                   [ 95%]
+apps\api\tests\test_store.py .s                                          [100%]
+
+============================== warnings summary ===============================
+..\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\fastapi\testclient.py:1
+  C:\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\fastapi\testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================== 42 passed, 1 skipped, 1 warning in 1.21s ===================

artifacts/maintenance-20260702-calendar-demo-script.log

@@ -0,0 +1,48 @@
+========================================================================
+AgentReplay - record -> compile -> run -> compare -> explain -> export
+========================================================================
+Workflow: calendar-demo   nodes=9  human_actions=7
+Driver: divergent   DeepSeek enabled: True
+
+Human path:
+   1. click         New event
+   2. click         Event title
+   3. fill          Event title = "Design review"
+   4. click         Start time
+   5. fill          Start time = "14:00"
+   6. click         Save event
+   7. assertVisible Event saved
+
+Agent path (driver = divergent):
+   1. click         New event
+   2. click         Event title
+   3. fill          Event title = "Design review"
+   4. click         Start time
+   5. fill          Start time = "14:00"
+   6. click         Special offer  <-- DIVERGES HERE
+
+First divergence : step 6 of 7
+Failure category : wrong-element
+Metrics          : success=False  step_accuracy=0.7143  wrong_clicks=1  recovered=False  replay_latency_ms=0
+
+AI summary (DeepSeek):
+  The agent clicked "Special offer" instead of "Save event" because it likely misidentified a visually similar or nearby promotional button, failing to distinguish the target action. To prevent this, implement exact text matching or use semantic selectors (e.g., `button:contains("Save event")`) and verify element purpose before clicking. (Step accuracy 71%, 1 wrong action(s); recovered: no.)
+
+Generated GitHub issue title:
+  Agent diverged at step 6 (wrong-element) in create a calendar event
+
+Generated Playwright test:
+
+import { test, expect } from "@playwright/test";
+
+test("create a calendar event", async ({ page }) => {
+  await page.getByRole("button", { name: "New event" }).click();
+  await page.getByRole("textbox", { name: "Event title" }).click();
+  await page.getByRole("textbox", { name: "Event title" }).fill("Design review");
+  await page.getByRole("textbox", { name: "Start time" }).click();
+  await page.getByRole("textbox", { name: "Start time" }).fill("14:00");
+  await page.getByRole("button", { name: "Save event" }).click();
+  await expect(page.getByText("Event saved")).toBeVisible();
+});
+
+========================================================================

artifacts/maintenance-20260702-demo-script-test-after.log

@@ -0,0 +1,13 @@
+C:\Users\caesa\AppData\Local\Programs\Python\Python313\Lib\site-packages\requests\__init__.py:113: RequestsDependencyWarning: urllib3 (2.5.0) or chardet (7.4.3)/charset_normalizer (3.4.4) doesn't match a supported version!
+  warnings.warn(
+============================= test session starts =============================
+platform win32 -- Python 3.13.5, pytest-8.4.2, pluggy-1.6.0
+rootdir: C:\AgentReplay\apps\api
+configfile: pyproject.toml
+plugins: anyio-4.11.0, langsmith-0.7.36, asyncio-1.4.0
+asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
+collected 1 item
+
+apps\api\tests\test_demo_script.py .                                     [100%]
+
+============================== 1 passed in 0.06s ==============================