diff --git a/docs/global.AGENTS.md b/docs/global.AGENTS.md index 4d941e1..1a0975f 100644 --- a/docs/global.AGENTS.md +++ b/docs/global.AGENTS.md @@ -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. diff --git a/skills/document/artifact-presenter/SKILL.md b/skills/document/artifact-presenter/SKILL.md index 42d4acb..f8adaff 100644 --- a/skills/document/artifact-presenter/SKILL.md +++ b/skills/document/artifact-presenter/SKILL.md @@ -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 --output html > mcat --output image > ``` -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. diff --git a/skills/tools/browser-harness/SKILL.md b/skills/tools/browser-harness/SKILL.md index e0a25c4..676b71f 100644 --- a/skills/tools/browser-harness/SKILL.md +++ b/skills/tools/browser-harness/SKILL.md @@ -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.