pi-ui-extend 1.0.23 → 1.0.28

package/external/pi-tools-suite/src/async-subagents/core/spawn.ts

@@ -6,7 +6,7 @@ import { selectSuitableToolsForModel } from "../../lib/tool-args.js";
 import { validateBasename } from "./paths.js";
 import { getPiInvocation } from "./pi-invocation.js";
 import { writePromptFile } from "./prompt.js";
-import { terminateProcess } from "./process.js";
+import { terminateProcessTree } from "./process.js";
 import { getAgentSessionDir, SUBAGENT_PARENT_SESSION_FILE, SUBAGENT_RETURN_SESSION_FILE, SUBAGENT_SESSION_FILE, writeParentSessionLink, writeSessionFileLink } from "./sessions.js";
 import { getAgentState } from "./state.js";
 import { writeStructuredResult } from "./structured-result.js";
@@ -31,6 +31,7 @@ const AGENT_TIMEOUT_KILL_GRACE_MS = 5_000;
 const AGENT_SETTLED_TERMINATE_GRACE_MS = 50;
 const AGENT_SETTLED_COMPLETION_FALLBACK_MS = 1_000;
 const EXIT_STDIO_FLUSH_GRACE_MS = 10;
+const PROGRESS_LOG_MAX_BYTES = 1024 * 1024;
 
 export function shouldPersistSubagentSessions(env: NodeJS.ProcessEnv = process.env): boolean {
 	return isTruthyEnv(env.ASYNC_SUBAGENTS_ENABLE_SESSIONS);
@@ -136,11 +137,16 @@ export function spawnAgent(
 	const invocation = getPiInvocation(piArgs);
 	const stderrStream = createDeferredFileWriter(stderrFile, logLimits.stderrMaxBytes, "stderr.log");
 	const transcriptStream = createBoundedFileWriter(transcriptFile, logLimits.eventsMaxBytes, "events.jsonl");
+	const progressStream = createBoundedFileWriter(path.join(agentDir, "progress.jsonl"), PROGRESS_LOG_MAX_BYTES, "progress.jsonl");
+	const writeProgress = (stage: string, details: Record<string, unknown> = {}) => {
+		progressStream.write(serializeJsonLine({ at: isoNow(), stage, ...details }));
+	};
 
 	const proc = spawn(invocation.command, invocation.args, {
 		cwd,
 		env: subagentEnvironment(process.env, task.subagentType === "browser-qa" ? agentDir : undefined),
 		stdio: ["pipe", "pipe", "pipe"],
+		detached: process.platform !== "win32",
 	});
 	proc.stdin.on("error", (error: NodeJS.ErrnoException) => {
 		if (error.code === "EPIPE") return;
@@ -156,18 +162,33 @@ export function spawnAgent(
 	let timeoutKillTimer: NodeJS.Timeout | undefined;
 	let agentSettledKillTimer: NodeJS.Timeout | undefined;
 	let agentSettledCompletionFallbackTimer: NodeJS.Timeout | undefined;
+	let processExitTreeKillTimer: NodeJS.Timeout | undefined;
 	let exitFinalizationTimer: NodeJS.Timeout | undefined;
+	let processTermination: { code: number | null; signal: NodeJS.Signals | null } | undefined;
+	let stdoutEnded = false;
 	const suppressedRpcEventCounts = new Map<string, number>();
+	const scheduleProcessTreeKill = (reason: string) => {
+		if (processExitTreeKillTimer) return;
+		processExitTreeKillTimer = setTimeout(() => {
+			try {
+				writeProgress("shutdown_signal", { reason, signal: "SIGKILL" });
+				terminateChildProcessTree(proc, "SIGKILL");
+			} catch {
+				/* process group may already be gone */
+			}
+		}, AGENT_SETTLED_COMPLETION_FALLBACK_MS);
+		processExitTreeKillTimer.unref?.();
+	};
 
 	const notifyComplete = (exitCode: number) => {
 		if (completionNotified) return;
 		if (exitCode !== 0) shouldKeepStderr = true;
 		completionNotified = true;
 		if (timeoutTimer) clearTimeout(timeoutTimer);
-		if (timeoutKillTimer) clearTimeout(timeoutKillTimer);
 		if (agentSettledKillTimer) clearTimeout(agentSettledKillTimer);
-		if (agentSettledCompletionFallbackTimer) clearTimeout(agentSettledCompletionFallbackTimer);
 		if (exitFinalizationTimer) clearTimeout(exitFinalizationTimer);
+		writeProgress("completed", { exitCode });
+		progressStream.end();
 		if (!fs.existsSync(agentDir)) {
 			onComplete?.({
 				runDir,
@@ -207,6 +228,7 @@ export function spawnAgent(
 
 	const finalizeCompletion = (code: number | null, signal: NodeJS.Signals | null) => {
 		if (completionNotified) return;
+		if (!timeoutKillTimer && !agentSettledCompletionFallbackTimer) scheduleProcessTreeKill("process_exit");
 		writeSuppressedRpcEventSummary(transcriptStream, suppressedRpcEventCounts);
 		const exitCode = resolveAgentExitCode({
 			timedOut,
@@ -233,19 +255,21 @@ export function spawnAgent(
 		agentSettledKillTimer = setTimeout(() => {
 			agentSettledKillTimer = undefined;
 			try {
-				terminateChildProcess(proc, "SIGTERM");
+				writeProgress("shutdown_signal", { reason: "agent_settled", signal: "SIGTERM" });
+				terminateChildProcessTree(proc, "SIGTERM");
 			} catch {
 				/* process may have exited before the graceful termination timer fired */
 			}
 		}, AGENT_SETTLED_TERMINATE_GRACE_MS);
 		agentSettledKillTimer.unref?.();
 		agentSettledCompletionFallbackTimer = setTimeout(() => {
-			if (completionNotified) return;
 			try {
-				terminateChildProcess(proc, "SIGKILL");
+				writeProgress("shutdown_signal", { reason: "agent_settled", signal: "SIGKILL" });
+				terminateChildProcessTree(proc, "SIGKILL");
 			} catch {
 				/* process may already be gone */
 			}
+			if (completionNotified) return;
 			proc.stdin.destroy();
 			proc.stdout?.destroy();
 			proc.stderr?.destroy();
@@ -261,6 +285,7 @@ export function spawnAgent(
 			if (completionNotified) return;
 			timedOut = true;
 			const timeoutMessage = `Sub-agent timed out after ${Math.round(timeoutMs / 1000)} seconds.`;
+			writeProgress("timeout", { timeoutMs });
 			if (fs.existsSync(agentDir)) {
 				fs.writeFileSync(path.join(agentDir, "timeout_ms"), String(timeoutMs), "utf-8");
 				fs.writeFileSync(path.join(agentDir, "timed_out_at"), isoNow(), "utf-8");
@@ -269,14 +294,15 @@ export function spawnAgent(
 				stderrStream.write(`${timeoutMessage}\n`);
 			}
 			try {
-				terminateChildProcess(proc, "SIGTERM");
+				writeProgress("shutdown_signal", { reason: "timeout", signal: "SIGTERM" });
+				terminateChildProcessTree(proc, "SIGTERM");
 			} catch {
 				/* process may have exited between the timer and signal */
 			}
 			timeoutKillTimer = setTimeout(() => {
-				if (completionNotified) return;
 				try {
-					terminateChildProcess(proc, "SIGKILL");
+					writeProgress("shutdown_signal", { reason: "timeout", signal: "SIGKILL" });
+					terminateChildProcessTree(proc, "SIGKILL");
 				} catch {
 					/* process may have exited after SIGTERM */
 				}
@@ -297,6 +323,8 @@ export function spawnAgent(
 			const event = JSON.parse(line) as RpcEventRecord;
 			const storedEvent = compactRpcEventForTranscript(event, Buffer.byteLength(line, "utf8"));
 			if (storedEvent) transcriptStream.write(serializeJsonLine(storedEvent));
+			const progressEvent = compactRpcEventForProgress(event);
+			if (progressEvent) writeProgress("rpc_event", progressEvent);
 			onRpcEvent?.(event);
 			const sessionFile = extractSessionFileFromEvent(event);
 			if (sessionFile) writeSessionFileLink(agentDir, sessionFile);
@@ -307,8 +335,13 @@ export function spawnAgent(
 			if (event.type === "response" && event.command === "prompt" && event.success === false) {
 				const errorText = typeof event.error === "string" ? event.error : "RPC prompt failed";
 				fs.writeFileSync(path.join(agentDir, "result.md"), errorText, "utf-8");
+				try {
+					terminateChildProcessTree(proc, "SIGTERM");
+				} catch {
+					/* process may have exited immediately after emitting the failure */
+				}
+				scheduleProcessTreeKill("prompt_failed");
 				notifyComplete(1);
-				terminateChildProcess(proc, "SIGTERM");
 				return;
 			}
 			if (event.type === "agent_end") {
@@ -359,10 +392,29 @@ export function spawnAgent(
 		},
 	});
 
-	proc.once("exit", (code, signal) => {
-		exitFinalizationTimer = setTimeout(() => finalizeCompletion(code, signal), EXIT_STDIO_FLUSH_GRACE_MS);
+	// Bun on Windows may emit the ChildProcess `close` event before the stdout
+	// Readable has delivered its final buffered `data`/`end` events. Gate process
+	// finalization on stdout itself so a trailing RPC failure cannot be mistaken
+	// for a clean exit.
+	const finalizeAfterStdout = () => {
+		if (!processTermination || !stdoutEnded || completionNotified || exitFinalizationTimer) return;
+		const { code, signal } = processTermination;
+		exitFinalizationTimer = setTimeout(
+			() => finalizeCompletion(code, signal),
+			EXIT_STDIO_FLUSH_GRACE_MS,
+		);
 		exitFinalizationTimer.unref?.();
+	};
+	const recordProcessTermination = (code: number | null, signal: NodeJS.Signals | null) => {
+		processTermination ??= { code, signal };
+		finalizeAfterStdout();
+	};
+	proc.stdout.once("end", () => {
+		stdoutEnded = true;
+		finalizeAfterStdout();
 	});
+	proc.once("exit", recordProcessTermination);
+	proc.once("close", recordProcessTermination);
 
 	proc.once("error", (error) => {
 		const message = String(error);
@@ -376,6 +428,11 @@ export function spawnAgent(
 		notifyComplete(1);
 	});
 
+	const pid = proc.pid!;
+	fs.writeFileSync(path.join(agentDir, "pid"), String(pid), "utf-8");
+	if (process.platform !== "win32") fs.writeFileSync(path.join(agentDir, "process_group"), String(pid), "utf-8");
+	writeProgress("spawned", { pid });
+
 	proc.stdin.write([
 		serializeJsonLine({
 			id: "sub_get_state",
@@ -388,6 +445,7 @@ export function spawnAgent(
 			...(promptImages ? { images: promptImages } : {}),
 		}),
 	].join(""));
+	writeProgress("prompt_sent");
 	// Keep stdin open while the RPC prompt is running. pi RPC mode treats stdin
 	// EOF as a shutdown request, while the prompt command itself is handled
 	// asynchronously after preflight. Closing stdin here can therefore terminate
@@ -395,9 +453,6 @@ export function spawnAgent(
 	// producing exit 0 with no result.md. The child is terminated explicitly after agent_settled,
 	// timeout, stop, or process error.
 
-	const pid = proc.pid!;
-	fs.writeFileSync(path.join(agentDir, "pid"), String(pid), "utf-8");
-
 	return { pid, agentDir, process: proc };
 }
 
@@ -423,9 +478,9 @@ function getAntigravityAuthExtensionPath(): string {
 	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "antigravity-auth", "index.ts");
 }
 
-function terminateChildProcess(proc: ChildProcess, signal: NodeJS.Signals): void {
+function terminateChildProcessTree(proc: ChildProcess, signal: NodeJS.Signals): void {
 	if (proc.pid) {
-		terminateProcess(proc.pid, signal as "SIGTERM" | "SIGINT" | "SIGKILL");
+		terminateProcessTree(proc.pid, signal as "SIGTERM" | "SIGINT" | "SIGKILL");
 		return;
 	}
 	proc.kill(signal);
@@ -603,6 +658,31 @@ function compactRpcEventForTranscript(event: RpcEventRecord, originalBytes: numb
 	return { type: event.type, bytes: originalBytes };
 }
 
+function compactRpcEventForProgress(event: RpcEventRecord): Record<string, unknown> | undefined {
+	if (event.type === "message_update" || event.type === "tool_execution_update") return undefined;
+	if (event.type === "response") {
+		return stripUndefined({
+			type: event.type,
+			command: typeof event.command === "string" ? event.command : undefined,
+			success: typeof event.success === "boolean" ? event.success : undefined,
+		});
+	}
+	if (event.type === "tool_execution_start" || event.type === "tool_execution_end") {
+		return stripUndefined({
+			type: event.type,
+			toolName: typeof event.toolName === "string" ? event.toolName : undefined,
+		});
+	}
+	if (event.type === "message_end") {
+		return stripUndefined({
+			type: event.type,
+			role: isRecord(event.message) && typeof event.message.role === "string" ? event.message.role : undefined,
+			stopReason: isRecord(event.message) && typeof event.message.stopReason === "string" ? event.message.stopReason : undefined,
+		});
+	}
+	return { type: event.type };
+}
+
 function suppressedRpcEventType(line: string): string | undefined {
 	if (line.includes('"type":"message_update"') || line.includes('"type": "message_update"')) return "message_update";
 	if (line.includes('"type":"tool_execution_update"') || line.includes('"type": "tool_execution_update"')) return "tool_execution_update";

package/external/pi-tools-suite/src/async-subagents/core/stop.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentState, getRunState } from "./state.js";
-import { terminateProcess } from "./process.js";
+import { terminateProcess, terminateProcessTree } from "./process.js";
 import { writeStructuredResult } from "./structured-result.js";
 import type { AgentState } from "./types.js";
 import { isoNow } from "./utils.js";
@@ -70,7 +70,9 @@ function stopAgent(runDir: string, agent: AgentState, signal: StopSignal): StopA
 	}
 
 	try {
-		terminateProcess(agent.pid, signal);
+		const ownsProcessGroup = fs.existsSync(path.join(runDir, agent.id, "process_group"));
+		if (ownsProcessGroup) terminateProcessTree(agent.pid, signal);
+		else terminateProcess(agent.pid, signal);
 		markStopped(runDir, agent.id, signal);
 		return {
 			...result,

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/SKILL.md

@@ -15,6 +15,13 @@ Never read, print, grep, copy, or edit credential values from
 
 ## Workflow
 
+Treat target discovery as a 30-second preflight and invoke the runner within 45
+seconds of starting. Use at most one runner invocation unless the task explicitly
+requests multiple auth profiles. If you cannot identify a reachable target and
+a supported deterministic assertion inside that preflight, return a structured
+`BLOCKED` result immediately. Do not consume the launcher budget on further
+source reading, server polling, capability probing, or retries.
+
 1. Resolve `scripts/browser-qa-runner.mjs` relative to this skill.
 2. Use the launcher-provided `$PI_SUBAGENT_AGENT_DIR/browser-qa/` workspace.
    The launcher creates its private `flows/` directory and the runner rejects
@@ -30,8 +37,9 @@ Never read, print, grep, copy, or edit credential values from
    safe profile traits make the choice unambiguous, or a public run proves that
    the requested page requires login.
 5. Inspect the target code and write a declarative JSONC flow under
-   `$PI_SUBAGENT_AGENT_DIR/browser-qa/flows/`. Never put credentials or
-   executable JavaScript in it.
+   `$PI_SUBAGENT_AGENT_DIR/browser-qa/flows/`. Never put credentials or raw
+   executable JavaScript in it. The `evaluate` action exposes only the safe
+   operations documented below; it does not accept expressions or scripts.
 6. Run public QA with
    `node <runner> run --base-url <url> --flow <flow.jsonc>`. The URL's exact
    origin becomes the fail-closed allowlist. Only for authenticated QA, add
@@ -39,7 +47,7 @@ Never read, print, grep, copy, or edit credential values from
    Profile id, URL, and flow path are non-secret; never pass credentials as
    arguments or environment variables.
 7. Report deterministic assertions and every artifact returned by the runner.
-   For each screenshot, video, or trace, emit a separate clickable Markdown
+   For each screenshot, video, trace, or retained download, emit a separate clickable Markdown
    link using its `uri` and also show its absolute `path`. Do this for failed
    runs too whenever `artifacts` is present; never report only `evidenceDir`.
    Visual inspection supplements assertions; it does not replace them.
@@ -56,9 +64,10 @@ Never read, print, grep, copy, or edit credential values from
   plus accessible `name`; `label`; `placeholder`; visible `text`; CSS only as a
   last resort. Use `exact: true` when similar elements could make a match
   ambiguous.
-- Let locator actions auto-wait. Use `waitFor` for an explicit UI state and use
-  `waitForTimeout` only for a short, unavoidable animation/debounce—not as a
-  substitute for an assertion. Set flow `timeoutMs` only as high as the target
+- Let locator actions auto-wait. Assertions retry until the flow timeout, so
+  prefer them over a preceding sleep. Use `waitFor` for an explicit setup state
+  and `waitForTimeout` only for short input settling or an unavoidable
+  animation/debounce. Set flow `timeoutMs` only as high as the target
   legitimately needs.
 - Place `authRejectedIf` immediately after navigation or any transition that
   may reveal expired authentication.
@@ -71,22 +80,97 @@ ambiguous failure, or deciding what evidence proves the result.
 
 ## Flow contract
 
-The flow is `{ "steps": [...] }` with at most 100 steps. Supported actions:
+The flow is `{ "steps": [...] }`, no larger than 16 MiB, with at most 100
+steps. The larger bound exists only for bounded in-memory upload payloads.
+Supported actions:
 
 - navigation: `goto`, `reload`, `waitFor`, `waitForTimeout`
 - interaction: `click`, `doubleClick`, `hover`, `fill`, `press`, `check`,
-  `uncheck`, `selectOption`
+  `uncheck`, `selectOption`, `wheel`, `evaluate`, `dragTo`, `uploadFiles`,
+  `openPopup`, `download`
 - assertions: `assertVisible`, `assertHidden`, `assertEnabled`,
   `assertDisabled`, `assertChecked`, `assertUnchecked`, `assertText`,
-  `assertValue`, `assertCount`, `assertURL`
+  `assertValue`, `assertAttribute`, `assertCount`, `assertURL`,
+  `assertDOMMetric`
 - evidence/auth: `screenshot`, `authRejectedIf`
 
 Locators accept one of `testId`, `role` (plus optional `name`), `label`,
 `placeholder`, `text`, or `css`; add `exact: true` where useful. String
 assertions require exactly one of `equals` or `includes`.
+`assertAttribute` additionally requires a bounded `attribute` name and is
+useful for `aria-*`, `data-*`, `href`, and similar observable state. All
+assertions retry until `timeoutMs` and report generic failures without exposing
+the actual text, value, or attribute content.
+
+Set an optional top-level `viewport` with integer `width` and `height` from
+`320×240` through `3840×2160`; the default is `1280×720`. The same dimensions
+are used for the browser viewport and recorded video.
+
+The top-level `environment` may set `locale`, `timezoneId`, `colorScheme`, and
+`reducedMotion`. Defaults are deterministic: `en-US`, `UTC`, `light`, and
+`reduce`. Color scheme accepts `light`, `dark`, or `no-preference`; reduced
+motion accepts `reduce` or `no-preference`. The resolved environment is returned
+in the result alongside the viewport.
+
+Triggering interactions (`click`, `doubleClick`, `press`, `check`, `uncheck`,
+and `selectOption`) may declare race-free expectations that are armed before
+the interaction:
+
+- `expectResponse`: exact origin-relative `path` (without query/fragment),
+  uppercase `method`, and integer `status` from 100 through 599;
+- `expectDialog`: `type` (`alert`, `beforeunload`, `confirm`, or `prompt`), a
+  nested `message` matcher with exactly one of `equals`/`includes`, and boolean
+  `accept`.
+
+The runner never records response bodies, headers, URLs, actual dialog text, or
+prompt defaults in observations or failure reasons. A mismatching dialog is
+dismissed so it cannot deadlock the browser.
+
+`dragTo` requires a source `locator` and `dropTarget`, with optional bounded
+`sourcePosition` and `dropPosition` `{ x, y }`. `uploadFiles` accepts only
+in-memory entries `{ name, mimeType, base64 }`; up to 10 files, 5 MiB each and
+10 MiB total. An empty array clears the input. Filesystem paths and directories
+are not supported.
+
+`download` atomically clicks its locator and requires a nested `filename`
+matcher. `maxBytes` defaults to 5 MiB and is capped at 25 MiB. Downloads are
+deleted after validation unless `retain: true` and a safe `name` are supplied;
+retained bytes appear in `artifacts.downloads` under a runner-generated `.bin`
+name. The runner cancels while its private copy grows past `maxBytes`, but this
+is an evidence-retention bound rather than a network-bandwidth guarantee because
+the browser may already hold temporary bytes. Retained bytes are scanned for
+configured authentication before publication. The actual server filename is
+never placed in diagnostics.
+
+`openPopup` atomically clicks a locator, captures a same-origin popup, and stores
+it under a safe `name` (maximum three). Target later actions with
+`{ "target": { "type": "popup", "name": "..." } }`. Target same-origin
+iframes with `{ "target": { "type": "frame", "locator": { ... } } }`; add
+`page` with a popup name for a frame inside that popup. Frame origin is checked
+from its live document before every scoped step. Cross-origin popups/frames are
+rejected. Popup recordings are returned as separate video artifacts.
+
+`wheel` accepts finite `deltaX`/`deltaY` values and requires at least one
+non-zero delta. With a locator, the runner hovers that element before sending
+the wheel input. Safe `evaluate` operations are:
+
+- `scrollTo`: optional locator plus numeric `x`/`y` or the string `"max"`;
+- `scrollBy`: optional locator plus numeric `deltaX`/`deltaY`;
+- `metrics`: optional locator plus an optional safe `name`; values are returned
+  in the runner's `observations` array.
+
+Element metrics are `scrollLeft`, `scrollTop`, `scrollWidth`, `scrollHeight`,
+`clientWidth`, `clientHeight`, `x`, `y`, `width`, and `height`. Page metrics are
+`scrollX`, `scrollY`, `scrollWidth`, `scrollHeight`, `clientWidth`,
+`clientHeight`, `viewportWidth`, and `viewportHeight`. Use `assertDOMMetric`
+with a `metric` and exactly one of `equals`, `greaterThan`,
+`greaterThanOrEqual`, `lessThan`, or `lessThanOrEqual` for a deterministic
+oracle. Raw JavaScript remains intentionally unsupported.
 
 ```jsonc
 {
+  "viewport": { "width": 844, "height": 847 },
+  "environment": { "locale": "en-GB", "timezoneId": "Europe/London", "colorScheme": "dark" },
   "steps": [
     { "action": "goto", "path": "/settings" },
     { "action": "authRejectedIf", "urlIncludes": "/login" },
@@ -94,7 +178,18 @@ assertions require exactly one of `equals` or `includes`.
       "action": "assertVisible",
       "locator": { "role": "heading", "name": "Settings", "exact": true }
     },
-    { "action": "click", "locator": { "testId": "save-settings" } },
+    { "action": "wheel", "locator": { "css": ".settings-panel" }, "deltaY": 500 },
+    {
+      "action": "assertDOMMetric",
+      "locator": { "css": ".settings-panel" },
+      "metric": "scrollTop",
+      "greaterThan": 0
+    },
+    {
+      "action": "click",
+      "locator": { "testId": "save-settings" },
+      "expectResponse": { "path": "/api/settings", "method": "PUT", "status": 200 }
+    },
     { "action": "assertText", "locator": { "testId": "toast" }, "includes": "Saved" },
     { "action": "screenshot", "name": "settings-saved" }
   ]
@@ -104,7 +199,7 @@ assertions require exactly one of `equals` or `includes`.
 For multiple profiles, invoke the runner separately. Every invocation gets an
 isolated browser context and exclusive evidence directory; the runner closes
 all owned browser resources on success and failure. Flows, screenshots, video,
-sanitized traces, and runner result manifests remain under
+sanitized traces, retained downloads, and runner result manifests remain under
 `$PI_SUBAGENT_AGENT_DIR/browser-qa/` so normal sub-agent shutdown or cleanup
 deletes them with the run directory. For form auth, recording starts on the login
 page and includes field filling and submission; password inputs remain masked,
@@ -132,8 +227,8 @@ claim that browser QA passed based on source inspection, unit tests, or a build.
 
 After any runner invocation that actually performed browser testing, include
 all non-empty `artifacts.screenshots`, `artifacts.videos`, and
-`artifacts.traces` groups in the final response. These links are mandatory so
-the user can open the evidence directly.
+`artifacts.traces`, and `artifacts.downloads` groups in the final response.
+These links are mandatory so the user can open the evidence directly.
 
 See `references/qa-auth.example.jsonc`, `references/qa-flow.example.jsonc`, and
 `references/qa-design.md`.

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/references/qa-design.md

@@ -47,6 +47,86 @@ observable intermediate state. Sleeping longer hides races instead of proving
 behavior. If a normal operation legitimately needs more time, adjust the flow's
 `timeoutMs` rather than inserting repeated sleeps.
 
+All assertion actions retry until that timeout. This makes an action followed
+directly by `assertText`, `assertVisible`, `assertURL`, or another assertion
+safe for asynchronously rendered outcomes. Use `assertAttribute` for
+observable state such as `aria-expanded`, `aria-invalid`, or `data-state`
+instead of reading DOM state through executable JavaScript.
+
+## Responsive and scrolling scenarios
+
+Set the flow's top-level `viewport` whenever the bug depends on a breakpoint or
+available height. Assert `viewportWidth` or `viewportHeight` with
+`assertDOMMetric` when the dimensions themselves are part of the proof; the
+runner also includes the applied viewport in its result.
+
+Use `wheel` to reproduce real pointer-wheel input. Add a locator when the wheel
+must target a nested scrolling container—the runner hovers it before sending
+the input. Because browser scrolling may be scheduled after the wheel event,
+wait only for a short known settling interval when a direct metric assertion is
+otherwise racy.
+
+Use safe `evaluate` `scrollTo`/`scrollBy` operations for deterministic setup or
+to distinguish input handling from layout behavior. Use the `metrics` operation
+to retain a named page/element snapshot in result `observations`, and use
+`assertDOMMetric` for pass/fail. Raw JavaScript expressions are intentionally
+excluded: flows remain declarative and cannot inspect authentication storage or
+execute arbitrary same-origin requests.
+
+## Deterministic browser environment
+
+Set top-level `environment` when locale, timezone, color scheme, or motion
+preferences can change the behavior. The runner otherwise uses stable defaults
+(`en-US`, `UTC`, `light`, `reduce`) instead of inheriting host settings. Prefer
+asserting product-visible copy or state derived from those settings; do not use
+screenshot pixels as the only oracle.
+
+## Causal network and dialog expectations
+
+Put `expectResponse` or `expectDialog` on the interaction that causes the event.
+The runner arms both listeners before the interaction, avoiding the race in a
+separate “click, then wait” sequence. Response expectations deliberately match
+only an exact allowlisted-origin pathname, HTTP method, and status. This proves
+that a matching request started and received a response within the action
+window without retaining its URL query, headers, or body.
+
+Dialog expectations match a fixed dialog type and exact/included message, then
+accept or dismiss it declaratively. A mismatch is dismissed before the step
+fails so the page cannot freeze. Actual event metadata is never included in
+failure diagnostics. Do not place secrets in expected messages or response
+paths even though the runner keeps diagnostics generic.
+
+## Drag, upload, and download scenarios
+
+Use `dragTo` for native DOM drag/drop and assert the resulting product state.
+Optional source/drop positions are relative bounded coordinates. Canvas-only,
+OS-native, or custom synthetic-event drag protocols remain unsupported; do not
+work around that with executable JavaScript.
+
+Uploads are memory-only base64 payloads declared in the flow. This intentionally
+prevents a flow from selecting arbitrary project files, credential config, or
+directories. Keep fixtures minimal and non-secret. An empty file list clears a
+file input.
+
+Use the atomic `download` action rather than clicking a download link directly.
+Always match the suggested filename and choose a tight `maxBytes`. Retain a
+download only when its contents are needed as evidence; otherwise the runner
+deletes it after validation. Retained downloads use generated private names,
+not server-provided paths, and are scanned for configured authentication before
+publication. `maxBytes` bounds the runner's private evidence copy and triggers
+cancellation while it grows, but it is not a network-bandwidth guarantee: the
+browser can receive temporary bytes before cancellation.
+
+## Same-origin frames and popups
+
+Use a scoped `target` for iframe or named popup interactions. The runner checks
+the live frame origin before every scoped step and checks a popup after it loads;
+both must remain in `allowedOrigins`. This supports embedded application UI and
+same-origin auxiliary windows without opening a route around the network guard.
+Cross-origin login, payment, and third-party widgets remain intentionally out of
+scope. Each popup adds a separate private video artifact, so open only the
+windows needed for the proof.
+
 ## Authentication transitions
 
 Add `authRejectedIf` directly after initial navigation and after transitions

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/references/qa-flow.example.jsonc

@@ -1,5 +1,12 @@
 {
   "timeoutMs": 15000,
+  "viewport": { "width": 844, "height": 847 },
+  "environment": {
+    "locale": "en-GB",
+    "timezoneId": "Europe/London",
+    "colorScheme": "dark",
+    "reducedMotion": "reduce"
+  },
   "steps": [
     { "action": "goto", "path": "/settings" },
     { "action": "authRejectedIf", "urlIncludes": "/login" },
@@ -12,8 +19,54 @@
       "locator": { "label": "Display name", "exact": true },
       "value": "QA Example"
     },
-    { "action": "click", "locator": { "testId": "save-settings" } },
+    { "action": "evaluate", "operation": "scrollTo", "locator": { "css": ".settings-panel" }, "y": 0 },
+    { "action": "wheel", "locator": { "css": ".settings-panel" }, "deltaY": 400 },
+    { "action": "assertDOMMetric", "locator": { "css": ".settings-panel" }, "metric": "scrollTop", "greaterThan": 0 },
+    { "action": "evaluate", "operation": "metrics", "locator": { "css": ".settings-panel" }, "name": "settings-scroll" },
+    {
+      "action": "dragTo",
+      "locator": { "testId": "available-widget" },
+      "dropTarget": { "testId": "enabled-widgets" }
+    },
+    {
+      "action": "uploadFiles",
+      "locator": { "label": "Import settings", "exact": true },
+      "files": [
+        { "name": "settings.json", "mimeType": "application/json", "base64": "eyJ0aGVtZSI6ImRhcmsifQ==" }
+      ]
+    },
+    {
+      "action": "click",
+      "locator": { "testId": "save-settings" },
+      "expectResponse": { "path": "/api/settings", "method": "PUT", "status": 200 },
+      "expectDialog": {
+        "type": "confirm",
+        "message": { "equals": "Save these settings?" },
+        "accept": true
+      }
+    },
+    { "action": "assertAttribute", "locator": { "testId": "save-settings" }, "attribute": "aria-busy", "equals": "false" },
     { "action": "assertText", "locator": { "testId": "toast" }, "includes": "Saved" },
+    { "action": "openPopup", "locator": { "testId": "preview-settings" }, "name": "preview" },
+    {
+      "action": "assertText",
+      "target": { "type": "popup", "name": "preview" },
+      "locator": { "role": "heading", "name": "Settings preview", "exact": true },
+      "equals": "Settings preview"
+    },
+    {
+      "action": "assertVisible",
+      "target": { "type": "frame", "locator": { "testId": "settings-help" } },
+      "locator": { "role": "heading", "name": "Settings help", "exact": true }
+    },
+    {
+      "action": "download",
+      "locator": { "testId": "export-settings" },
+      "filename": { "equals": "settings.json" },
+      "maxBytes": 1048576,
+      "retain": true,
+      "name": "settings-export"
+    },
     { "action": "screenshot", "name": "settings-saved" }
   ]
 }