specpi 0.11.2 → 0.13.0

package/docs/delegation/research.md

@@ -0,0 +1,216 @@
+# Evidence behind the delegation design
+
+Reviewed through 5 September 2026. This ledger distinguishes published studies,
+preprints, production accounts and API contracts. Design implications are our
+inferences. None of these sources benchmarks SpecPi's experimental implementation.
+The [implemented guide](README.md) and [calls/time protocol](protocol.md) describe its
+current behavior. The [archived design](design.md) preserves the broader proposal;
+publication of supporting research does not establish that either design improves
+SpecPi outcomes. Deterministic fixture tests and empirical evaluation are separate.
+
+## Existing seven-study foundation
+
+The [architecture article](../../site/single-agent/index.html) and its
+[reviewed chart data](../../site/charts/research-data.json) contain the detailed
+comparisons. The relevant implications for this design are:
+
+| Primary source                                                                                                                                        | Evidence relevant to the decision                                                                                  | Consequence for the protocol                                                                       |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| [Kim et al., Nature Machine Intelligence, 24 July 2026](https://www.nature.com/articles/s42256-026-01268-y)                                           | Coordination helps some task classes and degrades others under matched system ceilings; software samples are small | Keep a parent-only route and evaluate by task class; no universal capability cutoff                |
+| [Tran and Kiela, preprint v2, 11 April 2026](https://arxiv.org/html/2604.02460v2)                                                                     | Requested reasoning budget changes the single-versus-multi-agent ranking; actual accounting is imperfect           | Give the single agent the same additional resources before attributing gains to delegation         |
+| [Wunderlich et al., ACL SRW, July 2026](https://aclanthology.org/2026.acl-srw.1/)                                                                     | Configured ensembles can improve static-question accuracy at comparable modeled compute                            | Allow measured exceptions; distinguish ensembles from tool-using repository work                   |
+| [SwarmBench, preprint v1, 31 August 2026](https://arxiv.org/html/2608.30661v1)                                                                        | Swarm gains on several context-intensive tasks; only four task types have cost-matched comparisons                 | Prioritize bounded independent research; preserve metrics, model composition and cost denominators |
+| [Anthropic research system, 13 June 2025](https://www.anthropic.com/engineering/multi-agent-research-system)                                          | Parallel research can improve coverage, with substantially greater token use                                       | Budget source collection and synthesis together; no automatic assumption of cheaper outcomes       |
+| [OneFlow, preprint v1, 18 January 2026](https://arxiv.org/html/2601.12307v1)                                                                          | Useful workflow structure can survive single-conversation execution; latency changes depend on workflow            | Test serial structured execution as an alternative; track caching and latency independently        |
+| [MAST, NeurIPS 2025](https://papers.nips.cc/paper_files/paper/2025/hash/b1041e52d3be19f0a9bc491657488e4a-Abstract-Datasets_and_Benchmarks_Track.html) | Taxonomy covers design, coordination and verification failures; no matched single-agent control                    | Require explicit coverage, provenance, incomplete states and parent acceptance                     |
+
+## Additional empirical evidence
+
+### CooperBench: communication does not solve integration
+
+[CooperBench, v2, 26 January 2026](https://arxiv.org/html/2601.13295v2), Sections 2,
+4–5 and Appendix C/Table 5, evaluates 652 paired-feature tasks across 12 repositories
+and four languages. Tasks deliberately involve overlapping or interdependent code;
+agents work in separate containers. Communication reduced merge conflicts for four
+models without a significant cooperation-success gain for any model. GPT-5's
+successful-task counts were 315 solo versus 183 cooperative. Communication could consume
+up to 20% of execution steps.
+
+**Inference:** file separation, successful messaging and a clean merge are weak
+acceptance criteria. Keep one integration owner and specify behavior and interfaces,
+not only paths. A writing-worker proposal needs its own end-to-end evidence.
+
+**Limits:** the 100-action ceiling is per agent, not a demonstrated match of total
+spending. Conflict-heavy coding tasks do not characterize independent research scouts.
+Observed associations between early planning and fewer conflicts are not a causal
+evaluation of a planning protocol.
+
+### MTRouter: routing is a capability with a training cost
+
+[MTRouter, ACL final proceedings, July 2026](https://aclanthology.org/2026.acl-long.2045.pdf),
+Sections 3–4, Table 3 and Appendix A.2, studies sequential selection among six models.
+On 359 in-distribution HLE questions, GPT-5 achieved 25.1±1.6% accuracy at $61.8, versus
+26.0±2.3% at $35.0 for MTRouter. Values are mean±SD over three runs, and costs aggregate
+evaluated episodes. Both use a $2 episode ceiling and a 30-turn limit. Training-data
+collection used 29,693 trajectories at approximately $1,620.
+
+**Inference:** evaluate model routing separately from delegation. Use observed
+task-state evidence and account for training and switching costs; an untrained
+confidence heuristic is not the studied router.
+
+**Limits:** HLE and ScienceWorld are not repository coding; the small accuracy
+difference does not establish superiority. Exact switch probabilities differ between
+Figure 4 and its prose, so they are not used here. Cache-related explanations are not
+isolated causal measurements.
+
+### Paritok-4B: a smaller packet is not automatically a better packet
+
+[Paritok-4B, v1, 25 August 2026](https://arxiv.org/html/2608.24188v1), Section 6.2,
+Table 9 and Section 7, tests all 300 SWE-bench Lite instances. Its line-numbered
+compression configuration retained 27.8% of context tokens by per-instance
+macro-average. Uncompressed context solved 122/300 tasks (40.7%); compressed context
+solved 109/300 (36.3%). Patch-application failures were five versus sixteen. The paired
+solve difference had exact McNemar p=0.079.
+
+**Inference:** preserve retrieval of original source inside the grant. Count omissions
+and downstream accepted results, not just reduction in packet size. Select relevant
+material before adding another model to compress it.
+
+**Limits:** this is one tool-free Sonnet 4.5 request with oracle file context and
+diff re-anchoring, not a running coding agent. Non-significance does not demonstrate
+equivalence. Token reduction does not include compression, caching, latency or recovery
+costs and must not be presented as end-to-end savings.
+
+### OrchestraBench: recovery requires a useful change in state
+
+[OrchestraBench, v1, 5 August 2026](https://arxiv.org/html/2608.05263v1), Sections
+5.2–5.5, Table 8 and the trusted-state ablation, separates transient tool faults from
+latent semantic corruption in controlled arithmetic chains. Blind retry reproduced
+latent faults. In the N=180 trusted-state ablation, latent recovery fell from 0.67 to
+0.08 when the trusted upstream value was removed. The paired comparison used 24 pairs.
+
+**Inference:** a recovery request must identify the failed assumption and new evidence
+or validated state. Preserve incomplete and uncertain outcomes. A replay of the same
+instructions is not a recovery strategy.
+
+**Limits:** these are small synthetic mechanism probes; some outcomes are deterministic
+by construction. A simple TF-IDF comparator solved all ten adversarial routing cases.
+The study does not justify a dedicated LLM router or production reliability claims.
+
+## Additional production guidance
+
+### Cognition: useful collaborators around a single writer
+
+[Multi-Agents: What's Actually Working, 22 April 2026](https://cognition.com/blog/multi-agents-working)
+updates Cognition's earlier skepticism. It describes useful fresh-context review and
+capable-model consultation while retaining one writer. Its weaker-primary consultation
+experiment improved cost and speed but hit a quality ceiling because the primary
+struggled to recognize when and how to ask for help.
+
+**Inference:** preserve a strong parent; keep review context free of implementation
+rationalization; return concrete context requests when evidence is missing. Evaluate
+different-model consultation against a same-model fresh context. Do not infer that
+different context makes errors statistically independent.
+
+**Limits:** this is a production account, not a controlled budget-matched comparison.
+Full-history forking is one reported consultation technique, but SpecPi's privacy and
+explicit-packet boundary means it is not adopted here. No reported product bug count
+is used as a target for SpecPi.
+
+### Anthropic: keep the standing harness small
+
+[The new rules of context engineering, 24 July 2026](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models)
+reports reducing Claude Code's system prompt by over 80% for newer models without a
+measured loss on its coding evaluations. It emphasizes interface design, progressive
+disclosure, and avoiding repeated instructions.
+
+**Inference:** put constraints in the controller and broker; load short mode instructions
+only when needed. Do not add a second planner, repeated role prompts, or several pages
+of standing routing heuristics to every SpecPi session.
+
+**Limits:** this is model- and harness-specific engineering guidance. It is not evidence
+that deleting arbitrary safety checks, context, or instructions helps every model.
+
+## Narrow admission policy
+
+The implemented purposes are `review` of a frozen artifact and `scout` analysis of a
+bounded evidence question. Both may use selected-source tools. A review gets original
+requirements, relevant constraints and actual validation facts without the parent's
+reasoning or verdict. A scout needs selected sources and an independently checkable
+answer. A claimed parallel benefit also needs useful concurrent parent work; a fresh
+review or context-isolated analysis may run while the parent waits.
+
+These are **promising experimental scenarios, not measured SpecPi improvements**.
+SwarmBench's cost-matched gains on three of four task types do not establish an
+advantage for every investigation or this same-model snapshot-only implementation.
+Cognition's cross-frontier consultation does not validate a separate generic same-model
+consultation mode. Investigation and supplied-source research therefore share `scout`;
+there is no live-web or model-routing route.
+
+Small edits, routine lookups, coupled mutable work, repeated role answers, writing
+teams and blind retries remain outside this policy. Parallel parent tool calls remain
+an alternative to creating a worker. Mode/benefit checks and rejection of duplicate
+normalized questions constrain structure; they cannot certify semantic independence.
+The two-worker ceiling and all numeric quotas are engineering choices awaiting local
+evaluation, not empirical optima extracted from the papers.
+
+## Pi compatibility evidence
+
+The experimental SDK integration checks required public capabilities rather than an
+exact version list. Compatible Pi updates can activate without a SpecPi patch. Missing
+APIs and incompatible session/provider behavior detected by the runtime checks fail closed.
+The installer still bootstraps 0.84.4; its minimum-version contract is separate. The investigation used
+public tagged source and official documentation without live provider calls or private
+Pi state inspection. The current implementation uses public SDK `createAgentSession`,
+in-memory sessions and a fresh Pi `ModelRuntime` with standard authentication,
+environment and `models.json` resolution. Child transport/thinking budgets use configured
+global settings without project settings. Parent model/thinking are explicit, with Pi
+clamping; unsupported runtime-only authentication, selected extension-provider overrides,
+model-specific headers, startup proxy configuration and safe descriptor mismatches fail
+preflight. These integration limits leave the parent's setup unchanged.
+
+Pi runs the child loop. SpecPi admits each SDK invocation, disables retries/compaction
+and checks SDK-visible streaming. No ambient child resources or parent transcript are
+loaded. Parent request hooks, ephemeral runtime settings and session affinity are not
+automatically transferred. Full parent parity and hard raw-transport, hidden-attempt,
+memory or invoice bounds are not claimed. SDK contract tests and comparative outcomes
+remain distinct evidence requirements.
+
+| Contract                                | Primary source                                                                                                                     | Design consequence                                                                      |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Credential-blind completion facade      | [ModelRegistry at v0.84.4](https://github.com/earendil-works/pi/blob/v0.84.4/packages/coding-agent/src/core/model-registry.ts#L59) | Useful building block; does not expose the configured streaming pipeline                |
+| Runtime auth and request preparation    | [ModelRuntime](https://github.com/earendil-works/pi/blob/v0.84.4/packages/coding-agent/src/core/model-runtime.ts#L541)             | Keep credential handling inside Pi; preserve composed provider behavior                 |
+| Agent sessions and thinking translation | [SDK](https://github.com/earendil-works/pi/blob/v0.84.4/packages/coding-agent/src/core/sdk.ts#L283)                                | Use the Pi agent loop with explicit model/thinking; full parent policy is not automatic |
+| Tool interception                       | [AgentSession](https://github.com/earendil-works/pi/blob/v0.84.4/packages/coding-agent/src/core/agent-session.ts#L451)             | Built-in factories and `pi.exec()` do not automatically inherit Command Guard           |
+| Resource discovery                      | [ResourceLoader](https://github.com/earendil-works/pi/blob/v0.84.4/packages/coding-agent/src/core/resource-loader.ts#L36)          | In-memory session storage alone does not create a sterile child                         |
+| Tool scheduling                         | [Agent defaults](https://github.com/earendil-works/pi/blob/v0.84.4/packages/agent/src/agent.ts#L205)                               | Explicitly select execution policy and enforce each limit before work                   |
+| Error and usage semantics               | [Message types](https://github.com/earendil-works/pi/blob/v0.84.4/packages/ai/src/types.ts#L332)                                   | Inspect terminal status; do not double-count reasoning output or assume errors are free |
+| Session identity and navigation         | [Extension types](https://github.com/earendil-works/pi/blob/v0.84.4/packages/coding-agent/src/core/extensions/types.ts#L522)       | Invalidate actual navigation and task revisions, not every advancing leaf               |
+
+[Latest SDK](https://pi.dev/docs/latest/sdk), [latest extensions](https://pi.dev/docs/latest/extensions)
+and [latest provider documentation](https://pi.dev/docs/latest/custom-provider) were
+cross-checked. These are moving references, not proof of compatibility with a specific
+version. The [Pi 0.85.0 release notes](https://github.com/earendil-works/pi/releases/tag/v0.85.0)
+confirm its 4 September 2026 release. An isolated installation also reported CLI version
+0.85.0, prompting review of that released SDK alongside the tagged 0.84.4 baseline cited
+above. Isolated native and provider integration checks have passed on 0.85.0. These
+prove the exercised fixtures, not every provider/setup or comparative task benefit.
+The local activation failure on Pi 0.85.1 exposed the fragility of exact-version gating.
+The [0.85.1 tag](https://github.com/earendil-works/pi/releases/tag/v0.85.1) and an isolated
+installation were checked; its SDK session, agent-session and model-runtime modules
+match 0.85.0. The provider and ordinary-startup integration suites also pass on 0.85.1,
+including actual SDK tool replay, cancellation settlement, resource isolation and
+reload behavior. Unit fixtures accept newer and absent version identifiers while
+rejecting missing required APIs and unsupported provider routes. These synthetic
+identifiers do not claim that future SDK releases have been tested. Version labels
+now record test coverage rather than grant permission.
+Full repository and package validation remain separate release checks; API presence
+and a successful CLI version check cannot replace them.
+
+## What remains unproven
+
+The research does not establish an optimal default packet size, worker count, retry
+count, or routing threshold for SpecPi. It does not demonstrate production reliability
+for this implementation, a financial return, or a general advantage for parallel code
+writers. The target design and experimental protocol turn these uncertainties into
+testable choices. Runtime compatibility and measured user value remain distinct gates.

package/extensions/browser/core.d.mts

@@ -0,0 +1,64 @@
+import type * as Playwright from "playwright";
+
+export type Viewport = { width: number; height: number };
+export type ViewportInput = { preset?: "desktop" | "tablet" | "mobile"; width?: number; height?: number };
+export type PngImage = Viewport & { data: Buffer };
+export type BrowserRuntime = {
+    playwright: typeof Playwright;
+    PNG: {
+        new (size: Viewport): PngImage;
+        sync: { read(data: Buffer): PngImage; write(image: PngImage): Buffer };
+    };
+    pixelmatch: (
+        a: Buffer,
+        b: Buffer,
+        output: Buffer,
+        width: number,
+        height: number,
+        options: { threshold: number },
+    ) => number;
+};
+export declare const MAX_CAPTURE_DIMENSION: number;
+export declare const MAX_CAPTURE_PIXELS: number;
+export declare const MAX_INLINE_IMAGE_BYTES: number;
+export declare const MAX_PNG_BYTES: number;
+export declare const VIEWPORT_PRESETS: Readonly<Record<"desktop" | "tablet" | "mobile", Viewport>>;
+export declare const DEFAULT_DIFF_THRESHOLD: number;
+export declare const DEFAULT_MAX_DIFF_PIXEL_RATIO: number;
+export declare const MAX_VIEWPORT_PIXELS: number;
+export declare function assertDistinctPaths(entries: Array<[string, string]>): void;
+export declare function assertPngResourceBounds(data: Buffer, label?: string): Viewport;
+export declare function readPngDimensions(data: Buffer, label?: string): Viewport;
+export declare function comparePngBuffers(
+    a: Buffer,
+    b: Buffer,
+    runtime: Pick<BrowserRuntime, "PNG" | "pixelmatch">,
+    options?: { threshold?: number; maxDiffPixelRatio?: number },
+): {
+    pass: boolean;
+    dimensionsMatch: boolean;
+    baseline: Viewport;
+    current: Viewport;
+    diffPixels: number;
+    diffPixelRatio: number;
+    diffBuffer: Buffer;
+    threshold: number;
+    maxDiffPixelRatio: number;
+};
+export declare function getAgentDir(extensionUrl: string): string;
+export declare function loadBrowserRuntime(runtimeDir: string): Promise<BrowserRuntime>;
+export declare function makeArtifactPath(
+    agentDir: string,
+    sessionId: string | undefined,
+    kind: string,
+    extension?: string,
+): string;
+export declare function sanitizeArtifactSegment(value: string): string;
+export declare function normalizeBrowserUrl(value: string): string;
+export declare function publishBuffer(
+    file: string,
+    data: Buffer,
+    options?: { overwrite?: boolean; signal?: AbortSignal },
+): Promise<void>;
+export declare function resolveUserPath(cwd: string, value: string, label?: string): string;
+export declare function resolveViewport(input?: ViewportInput): Viewport;

package/extensions/browser/diagnostics.ts

@@ -0,0 +1,275 @@
+import crypto from "node:crypto";
+import type { ConsoleMessage, Page, Request, Response } from "playwright";
+
+export const DIAGNOSTIC_CATEGORIES = ["pageerror", "console", "requestfailed", "http"] as const;
+export type DiagnosticCategory = (typeof DIAGNOSTIC_CATEGORIES)[number];
+export const MAX_DIAGNOSTIC_RECORDS = 200;
+export const MAX_DIAGNOSTIC_BYTES = 256 * 1024;
+export const MAX_RECORD_BYTES = 2048;
+
+export function boundedInteger(value: number | undefined, fallback: number, maximum: number, minimum = 1): number {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < minimum || result > maximum) {
+        throw new Error(`Expected an integer from ${minimum} to ${maximum}.`);
+    }
+
+    return result;
+}
+
+function prefix(value: string, limit: number): string {
+    return value.slice(0, limit).toWellFormed();
+}
+
+function diagnosticUrl(value: string) {
+    try {
+        const url = new URL(value.slice(0, 16384));
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return { text: "[non-http location]", truncated: false };
+        }
+
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+
+        return { text: prefix(url.href, 300), truncated: value.length > 16384 || url.href.length > 300 };
+    } catch {
+        return { text: "[location omitted]", truncated: value.length > 16384 };
+    }
+}
+
+export function sanitizeUrl(value: string): string {
+    return diagnosticUrl(value).text;
+}
+
+/** Best effort only. Application messages and URL paths may contain arbitrary secrets. */
+function diagnosticText(value: string, limit = 700) {
+    // Bound processing as well as retention. Redact before taking the final display prefix.
+    let locationTruncated = false;
+    const sanitized = value
+        .slice(0, 16384)
+        .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\|$)/gu, " ")
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, " ")
+        .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, " ")
+        .replace(/https?:\/\/[^\s<>"']+/giu, (url) => {
+            const location = diagnosticUrl(url);
+            locationTruncated ||= location.truncated;
+
+            return location.text;
+        })
+        .replace(/\b(?:bearer|basic)\s+[^\s,;]+/giu, "[authorization redacted]")
+        .replace(
+            /(["']?(?:password|passwd|secret|token|api[_-]?key|authorization|cookie|credential|access[_-]?key)["']?\s*[:=]\s*)(?:"[^"]*(?:"|$)|'[^']*(?:'|$)|[^\s,;]+)/giu,
+            "$1[redacted]",
+        );
+
+    return {
+        text: prefix(sanitized, limit),
+        truncated: value.length > 16384 || sanitized.length > limit || locationTruncated,
+    };
+}
+
+export function sanitizeDiagnostic(value: string, limit = 700): string {
+    return diagnosticText(value, limit).text;
+}
+
+type DiagnosticRecord = {
+    sequence: number;
+    navigation: number;
+    category: DiagnosticCategory;
+    message: string;
+    url: string;
+    method?: string;
+    status?: number;
+    resourceType?: string;
+    truncated: boolean;
+};
+export type DiagnosticQuery = {
+    maxEntries?: number;
+    maxChars?: number;
+    category?: DiagnosticCategory;
+    cursor?: string;
+    clear?: boolean;
+};
+
+export class BrowserDiagnostics {
+    private context = crypto.randomUUID();
+    private sequence = 0;
+    private navigation = 0;
+    private floor = 0;
+    private dropped = 0;
+    private bytes = 0;
+    private records: DiagnosticRecord[] = [];
+
+    reset(): void {
+        this.context = crypto.randomUUID();
+        this.sequence = 0;
+        this.navigation = 0;
+        this.floor = 0;
+        this.dropped = 0;
+        this.bytes = 0;
+        this.records = [];
+    }
+
+    navigated(): void {
+        this.navigation += 1;
+    }
+
+    record(
+        category: DiagnosticCategory,
+        message: string,
+        url = "",
+        extra: { method?: string; status?: number; resourceType?: string } = {},
+    ): void {
+        const clean = diagnosticText(message);
+        const location = url ? diagnosticUrl(url) : undefined;
+        const method = extra.method ? diagnosticText(extra.method, 20) : undefined;
+        const resourceType = extra.resourceType ? diagnosticText(extra.resourceType, 30) : undefined;
+        const entry: DiagnosticRecord = {
+            sequence: ++this.sequence,
+            navigation: this.navigation,
+            category,
+            message: clean.text,
+            url: location?.text ?? "",
+            method: method?.text,
+            status: extra.status,
+            resourceType: resourceType?.text,
+            truncated:
+                clean.truncated ||
+                location?.truncated === true ||
+                method?.truncated === true ||
+                resourceType?.truncated === true,
+        };
+        while (Buffer.byteLength(JSON.stringify(entry)) > MAX_RECORD_BYTES) {
+            entry.truncated = true;
+            if (entry.message.length) {
+                entry.message = prefix(entry.message, Math.floor(entry.message.length / 2));
+            } else {
+                entry.url = prefix(entry.url, Math.floor(entry.url.length / 2));
+            }
+        }
+
+        this.records.push(entry);
+        this.bytes += Buffer.byteLength(JSON.stringify(entry));
+        while (this.records.length > MAX_DIAGNOSTIC_RECORDS || this.bytes > MAX_DIAGNOSTIC_BYTES) {
+            const removed = this.records.shift()!;
+            this.bytes -= Buffer.byteLength(JSON.stringify(removed));
+            this.floor = removed.sequence;
+            this.dropped += 1;
+        }
+    }
+
+    read(query: DiagnosticQuery = {}) {
+        const maxEntries = boundedInteger(query.maxEntries, 50, 100);
+        const maxChars = boundedInteger(query.maxChars, 12000, 30000, 1000);
+        if (query.category !== undefined && !DIAGNOSTIC_CATEGORIES.includes(query.category)) {
+            throw new Error("Unknown diagnostic category.");
+        }
+
+        if (query.clear !== undefined && typeof query.clear !== "boolean") {
+            throw new Error("clear must be boolean.");
+        }
+
+        let after = 0;
+        let contextChanged = false;
+        if (query.cursor !== undefined) {
+            if (typeof query.cursor !== "string" || !/^[\da-f-]{36}:\d{1,16}$/u.test(query.cursor)) {
+                throw new Error("Invalid diagnostics cursor.");
+            }
+
+            const [context, sequence] = query.cursor.split(":");
+            contextChanged = context !== this.context;
+            after = contextChanged ? 0 : Number(sequence);
+            if (!Number.isSafeInteger(after) || after > this.sequence) {
+                throw new Error("Invalid diagnostics cursor sequence.");
+            }
+        }
+
+        const candidates = this.records.filter(
+            (entry) => entry.sequence > after && (!query.category || entry.category === query.category),
+        );
+        const result = {
+            notice: "Untrusted application output; redaction is best-effort. Empty results do not prove application health. Active page only.",
+            context: this.context,
+            contextChanged,
+            cursorGap: contextChanged || after < this.floor,
+            droppedRecords: this.dropped,
+            retainedRecords: this.records.length,
+            retainedBytes: this.bytes,
+            clearedRecords: query.clear ? this.records.length : 0,
+            hasMore: false,
+            nextCursor: `${this.context}:${this.sequence}`,
+            records: [] as DiagnosticRecord[],
+        };
+        for (const entry of candidates.slice(0, maxEntries)) {
+            result.records.push({ ...entry });
+            if (JSON.stringify(result).length > maxChars) {
+                if (result.records.length > 1) {
+                    result.records.pop();
+                    break;
+                }
+
+                const first = result.records[0];
+                while (JSON.stringify(result).length > maxChars) {
+                    first.truncated = true;
+                    if (first.message.length) {
+                        first.message = prefix(first.message, Math.floor(first.message.length / 2));
+                    } else {
+                        first.url = prefix(first.url, Math.floor(first.url.length / 2));
+                    }
+                }
+            }
+        }
+
+        result.hasMore = result.records.length < candidates.length;
+        if (result.hasMore) {
+            result.nextCursor = `${this.context}:${result.records.at(-1)?.sequence ?? after}`;
+        }
+
+        if (query.clear) {
+            // Atomic synchronous read-and-clear of the entire buffer, including filtered/unreturned records.
+            this.records = [];
+            this.bytes = 0;
+            this.floor = this.sequence;
+        }
+
+        return result;
+    }
+
+    attach(page: Page): () => void {
+        const onError = (error: Error) => this.record("pageerror", error.message);
+        const onConsole = (message: ConsoleMessage) => {
+            if (message.type() === "error") {
+                this.record("console", message.text(), message.location().url);
+            }
+        };
+
+        const onRequest = (request: Request) =>
+            this.record("requestfailed", request.failure()?.errorText ?? "Request failed", request.url(), {
+                method: request.method(),
+                resourceType: request.resourceType(),
+            });
+        const onResponse = (response: Response) => {
+            if (response.status() >= 400) {
+                const request = response.request();
+                this.record("http", `HTTP ${response.status()}`, response.url(), {
+                    status: response.status(),
+                    method: request.method(),
+                    resourceType: request.resourceType(),
+                });
+            }
+        };
+
+        page.on("pageerror", onError);
+        page.on("console", onConsole);
+        page.on("requestfailed", onRequest);
+        page.on("response", onResponse);
+
+        return () => {
+            page.off("pageerror", onError);
+            page.off("console", onConsole);
+            page.off("requestfailed", onRequest);
+            page.off("response", onResponse);
+        };
+    }
+}