update global AGENTS with test updates, update browser-harness and artifact presenter for html view

2026-08-27 00:55:26 -04:00
parent cf9770b71d
commit 4bbd6a6d06
3 changed files with 49 additions and 7 deletions
@@ -61,7 +61,8 @@ Below you will find my preferences so that we can be more aligned as we work tog

 ## Testing

- Always write tests for any changed behavior.
+- Write appropriate tests for changed behavior. 
+- Do not add tests unnecessarily. Simple straightforward code does not need a unit test for every single branch.
 - Tests should be focused. Endless smoke tests, or regression tests for feature removals, are not as useful.
 - Always run tests before commits and do not report them successful unless all tests have actually executed.
 - E2E tests must be written and validate with realistic data. Garbage In, Garbage Out. Test data needs to emulate, or be, real data.
@@ -1,11 +1,11 @@
 ---
 name: artifact-presenter
-description: Present any single local file the user needs to review, including documents, source, archives, PDFs, images, and videos, through mcat in a reusable Herdr pane. Also use for structured long-form reports, plans, ADRs, reviews, and summaries unless the user requests inline chat.
+description: Present local artifacts for review: use Browser Harness for interactive web artifacts, especially HTML, and mcat for non-web files, Markdown, and static source.
 ---

 # Artifact presenter

-Present reviewable files and substantial generated content in a reusable terminal document pane instead of duplicating the complete artifact in chat.
+Present reviewable files and substantial generated content through the appropriate viewer instead of duplicating the complete artifact in chat.

 ## Choose the artifact

@@ -23,6 +23,11 @@ Treat an explicit destination and format as authoritative. For generated content

 Keep ordinary explanations, code diffs, logs, multi-file comparisons, and user-requested inline responses in chat. Present a file only when it is a user-facing review artifact, not merely because the agent read it during investigation.

+Choose the presentation path:
+
+- **Interactive web artifacts, especially `.html`:** use the Browser Harness/Browser Use-backed workflow.
+- **Non-web files, Markdown, and static source:** use mcat in the reusable Herdr pane.
+
 Completion criterion: select exactly one existing or generated artifact path before presentation.

 ## Prepare generated content
@@ -31,11 +36,17 @@ Write the complete deliverable to the selected path. Keep it self-contained: the

 Preserve repository documentation conventions. Creating a presentation artifact under `/tmp` does not authorize editing repository files when the request is otherwise read-only.

-When presenting an existing file, pass the original file directly to mcat. Do not create a converted copy merely for display.
+When presenting an existing non-web file, pass the original file directly to mcat. Do not create a converted copy merely for display.

 Completion criterion: the selected file exists and contains the complete review artifact.

-## Present with mcat
+## Present interactive web artifacts
+
+Load and follow the [`browser-harness`](../browser-harness/SKILL.md) skill. Open the local artifact URL in a real browser through the Browser Harness/Browser Use-backed workflow, then verify the browser target reports the artifact URL and page title. When normal Chrome attachment is unavailable, use browser-harness's documented local HTML fallback.
+
+Completion criterion: the active browser target reports the local artifact URL and page title.
+
+## Present non-web artifacts with mcat

 Run the helper using its absolute path resolved from this skill directory:

@@ -57,7 +68,7 @@ mcat <input> --output html > <output.html>
 mcat <input> --output image > <output.png>
 ```

-Use an explicit output path and preserve the source file. Present the resulting single file through the helper when the user needs to review it.
+Use an explicit output path and preserve the source file. Present the resulting single file through the matching presentation path above when the user needs to review it.

 ## Respond concisely

@@ -65,6 +76,7 @@ Return:

 - a one- to three-sentence result summary;
 - the artifact path;
- whether the reusable mcat pane was opened or reused, or why presentation fell back to the file only.
+- for interactive web artifacts, that Browser Harness presented the artifact and verified its URL/title;
+- for other artifacts, whether the reusable mcat pane was opened or reused, or why presentation fell back to the file only.

 Do not repeat the complete artifact in chat. Honor a later request to paste any section inline.
@@ -46,6 +46,35 @@ chrome://inspect/#remote-debugging

 Ask the user to tick "Allow remote debugging for this browser instance" and click Allow if Chrome shows a permission popup. Then retry the same `browser-harness` command.

+## Local HTML fallback (Vivaldi)
+
+Use this fallback only to present a local HTML artifact when normal Chrome attachment is unavailable. An existing Vivaldi can absorb `vivaldi --remote-debugging-port=9222`, causing its launcher to exit without exposing CDP. Launch a separate Vivaldi process with an isolated profile. For a persistent launch, use the coding harness's tracked background-task facility when available rather than shell `&`:
+
+```bash
+vivaldi --remote-debugging-port=9222 --user-data-dir=/tmp/pi-vivaldi-cdp --no-first-run file:///absolute/path/to/artifact.html
+```
+
+Reload the harness daemon before connecting so it drops any stale Chrome connection:
+
+```bash
+browser-harness --reload
+BU_CDP_URL=http://127.0.0.1:9222 browser-harness <<'PY'
+print(page_info())
+PY
+```
+
+If `page_info()` initially times out on Vivaldi's blank attached target, inspect the targets, open the artifact in a new tab, and verify again:
+
+```bash
+BU_CDP_URL=http://127.0.0.1:9222 browser-harness <<'PY'
+print(cdp('Target.getTargets'))
+new_tab('file:///absolute/path/to/artifact.html')
+print(page_info())
+PY
+```
+
+Completion criterion: `page_info()` reports the artifact's file URL and page title.
+
 ## Remote Browsers

 Use Browser Use cloud for headless servers, parallel sub-agents, or isolated work.