@reticlehq/browser 2.13.0 → 2.14.0

package/dist/observers/ipc.js

@@ -1,32 +1,9 @@
 import { BlindSpotKind, EventType, IPC_URL_SCHEME, IpcStatus, NetInitiator, RETICLE_IPC_GLOBAL, RETICLE_TAURI_CAPTURE_COMMAND, } from '@reticlehq/core';
 import { observeSafely } from './types.js';
-/**
- * How Tauri v2 reports a command's verdict. The transport answers HTTP 200 whether the Rust command
- * returned Ok or Err — the verdict is in this response header, which Tauri explicitly CORS-exposes so
- * JS may read it. Without translating it, every failed command is recorded as a successful request.
- */
 const TAURI_RESPONSE_HEADER_NAME = 'Tauri-Response';
 const TAURI_RESPONSE_ERROR = 'error';
-/** Rust/IPC vocabulary rather than HTTP's, so the text never claims a transport status it lacks. */
 const IPC_STATUS_TEXT = { OK: 'Ok', ERROR: 'Err' };
-/**
- * Tauri's IPC endpoint. The last path segment is the command name.
- *
- * TWO spellings, because Tauri v2 uses a different one per platform and matching only the first is a
- * silent false green on Windows: macOS/Linux get the custom scheme `ipc://localhost/archive_todo`,
- * while Windows (and Android) need a real http origin and get
- * `http://ipc.localhost/archive_todo` — the hostname `desktop-doctor` already tells people to put in
- * their CSP. Unmatched, a Windows `invoke` was recorded as an ordinary HTTP request, so the
- * `Tauri-Response` translation never ran and every command that returned `Err` was banked as a
- * successful 200. `.localhost` is reserved for loopback by RFC 6761, so this can never match a
- * remote host.
- */
 const TAURI_IPC_URL = /^(?:ipc:\/\/[^/]*|https?:\/\/ipc\.localhost(?::\d+)?)\/(.+)$/;
-/**
- * Fields to override on a NET_REQUEST that turned out to be a Tauri IPC call, or null when the
- * request was ordinary HTTP. Pure — the network observer calls this with the response header it
- * already holds, so IPC knowledge stays in this file.
- */
 export function ipcNetOverrides(url, header) {
     const match = TAURI_IPC_URL.exec(url);
     const command = match?.[1];
@@ -34,53 +11,23 @@ export function ipcNetOverrides(url, header) {
         return undefined;
     const ok = header(TAURI_RESPONSE_HEADER_NAME) !== TAURI_RESPONSE_ERROR;
     return {
-        // Normalize `ipc://localhost/archive_todo` to `ipc://archive_todo`, so a Tauri command and an
-        // Electron channel read identically to the agent and to a saved flow's assertions.
         url: `${IPC_URL_SCHEME}${command}`,
         initiator: NetInitiator.IPC,
         method: NetInitiator.IPC,
         ok,
         status: ok ? IpcStatus.OK : IpcStatus.ERROR,
-        // Overwrite the TRANSPORT's statusText. Tauri's fetch genuinely answered 200/"OK", so letting it
-        // through beside a synthetic 500 produced a record that contradicted itself — `status: 500,
-        // statusText: "OK"` reads as nonsense to anyone seeing it cold. The record must tell one story,
-        // and the story that matters is the command's verdict, not the pipe it travelled down.
         statusText: ok ? IPC_STATUS_TEXT.OK : IPC_STATUS_TEXT.ERROR,
     };
 }
-/**
- * Is this fetch Reticle's OWN desktop call rather than the app's?
- *
- * Tauri has no preload stage, so `reticle_screenshot` reaches the shell the only way it can: an
- * `invoke` — and an invoke IS a fetch to the `ipc://` protocol, straight through the patch the
- * network observer installed. So the observer recorded its own screenshots as app IPC calls, and
- * because `IPC` counts as a mutating method, three concurrent captures inside one action window came
- * back to the agent as `duplicate-request`: "the same write fired 3 times", against an app that had
- * never made the call. Accusing a correct app of a double submit is the most damaging thing a
- * verification tool can do, and here the tool was the one submitting.
- *
- * Electron never had this problem — its preload captures through the UNPATCHED invoke for exactly
- * this reason — and the bridge's own WebSocket is skipped on the same principle (`isBridgeSocket`).
- * The capture command is the SDK's whole Tauri-side surface, so matching it is the whole rule.
- */
 export function isReticleOwnIpc(url) {
     return TAURI_IPC_URL.exec(url)?.[1] === RETICLE_TAURI_CAPTURE_COMMAND;
 }
-/**
- * Is this page an Electron renderer? Read off the user agent, which Electron stamps and which is
- * available whether or not the preload ran — the whole point is to recognise a renderer that has
- * NOT been instrumented.
- */
 function isElectronRenderer() {
     return navigator.userAgent.includes('Electron');
 }
 export function installIpc(emit, options = {}) {
     const channel = window[RETICLE_IPC_GLOBAL];
     if (typeof channel?.subscribe !== 'function') {
-        // No shim — but on Electron that is not "nothing to observe", it is "everything unobserved".
-        // Tauri needs no shim (its invoke travels as a fetch) and a web page has no IPC at all, so only
-        // Electron gets the declaration. Saying nothing here is what let a missing preload line read as
-        // a clean, empty network view for a whole app.
         if (isElectronRenderer())
             emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.UNOBSERVED_IPC, count: 1 });
         return () => undefined;
@@ -97,13 +44,7 @@ export function installIpc(emit, options = {}) {
                 });
                 return;
             }
-            // A one-way `send` that did not throw has NO verdict — the renderer never learns whether the
-            // main process handled it. Emitting `ok/status` anyway would manufacture the success nobody
-            // reported, so both are omitted and `oneWay` says why. `reticle_network { ok }` then matches
-            // such a record in neither direction, which is the honest answer to "did it work".
             const verdictless = true === record.oneWay && record.ok === undefined;
-            // Declared, not inferred: the server cannot tell "no verdict" from "not yet settled" without
-            // being told, and a send with nothing to observe must not read as a clean green.
             if (verdictless)
                 emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.VERDICTLESS_SEND, count: 1 });
             const ok = true === record.ok;
@@ -116,9 +57,6 @@ export function installIpc(emit, options = {}) {
                 durationMs: record.durationMs ?? 0,
                 initiator: NetInitiator.IPC,
                 ...(record.error === undefined ? {} : { error: record.error }),
-                // Size travels ALWAYS, bodies only on opt-in. The split matters: the verdict layer reports "a
-                // write returned ok and its payload went unread" from the size alone, and it cannot infer that
-                // from an absent field — an unread payload and an empty one would look identical.
                 ...(record.responseSize === undefined ? {} : { responseSize: record.responseSize }),
                 ...(true === options.captureBodies
                     ? {
@@ -130,9 +68,6 @@ export function installIpc(emit, options = {}) {
             });
         });
     });
-    // A REAL removal, so teardown leaves the app as it found it. The preload's `invoke` patch stays
-    // deliberately — it is a pass-through with no effect once no subscriber remains, and un-patching
-    // mid-flight would strand any call already inside the wrapper.
     return () => {
         channel.unsubscribe?.(token);
     };

package/dist/observers/navigation.d.ts

@@ -0,0 +1,2 @@
+import type { Emit, Teardown } from './types.js';
+export declare function installNavigation(emit: Emit): Teardown;

package/dist/observers/navigation.js

@@ -0,0 +1,33 @@
+import { EventType, NetInitiator } from '@reticlehq/core';
+const REPORTED_TYPES = new Set(['navigate', 'reload', 'back_forward']);
+function navigationEntry() {
+    try {
+        const [first] = performance.getEntriesByType('navigation');
+        return first;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function installNavigation(emit) {
+    const entry = navigationEntry();
+    const type = entry?.type;
+    const url = entry?.name;
+    if (entry === undefined || 'string' !== typeof url || 0 === url.length)
+        return () => undefined;
+    if ('string' !== typeof type || !REPORTED_TYPES.has(type))
+        return () => undefined;
+    const status = entry.responseStatus;
+    const known = 'number' === typeof status && status > 0;
+    emit(EventType.NET_REQUEST, {
+        id: `doc-${String(Math.round(entry.duration ?? 0))}`,
+        method: 'GET',
+        url,
+        initiator: NetInitiator.DOCUMENT,
+        durationMs: Math.round(entry.duration ?? 0),
+        ...(known ? { status, ok: status < 400 } : {}),
+        navigationType: type,
+        ...('number' === typeof entry.transferSize ? { transferSize: entry.transferSize } : {}),
+    });
+    return () => undefined;
+}

package/dist/observers/network-body.d.ts

@@ -1,34 +1,11 @@
-/**
- * Is this response body still arriving after the request itself resolved?
- *
- * STRUCTURAL, not a content-type allowlist. The first version listed `x-component|x-ndjson|
- * application/stream` — which is to say "Next.js RSC, plus two guesses". It closed the exact defect
- * it was written against and left every other streamed response as invisible as before: a chunked
- * `application/json` from a token API, a streamed HTML document, an export assembled server-side.
- * Fixing one app's symptom and calling the class solved is how a false green comes back wearing
- * different clothes.
- *
- * The real signal is on the wire: a response with a BODY and no `content-length` is being sent
- * chunked, which is the definition of "the server is still writing". `content-length` present means
- * the size was known up front and the body cannot grow.
- *
- * Deliberately independent of content type, with one exception above for streams that never end.
- */
 export declare function isStreamingBody(contentType: string | null, contentLength: string | null): boolean;
-/**
- * Resolve with the body text, or `undefined` if it takes too long.
- *
- * The app is already awaiting our patched fetch, so any unbounded read here is a hang in the host app.
- * Losing an observation is always preferable to freezing the page being observed.
- */
 export declare function withBodyDeadline(read: Promise<string>): Promise<string | undefined>;
 export declare function isCapturableType(contentType: string | null): boolean;
-/**
- * Redact + cap a body for the agent transcript. JSON is parsed and run through the same
- * sanitizeForTransport redaction used for state (sensitive keys -> [REDACTED]); every other text body
- * (and JSON that didn't parse) goes through redactText so form/plain-text credentials can't leak.
- * Returns the (possibly truncated) body plus whether it was cut.
- */
+export declare function shouldCaptureErrorBody(status: number, enabled: boolean): boolean;
+export declare function projectErrorBody(rawText: string, contentType: string | null): {
+    body: string;
+    truncated: boolean;
+};
 export declare function projectBody(rawText: string, contentType: string | null): {
     body: string;
     truncated: boolean;

package/dist/observers/network-body.js

@@ -1,74 +1,16 @@
-/**
- * Response/request BODY projection for the network observer.
- *
- * Split out of network.ts, which had grown to hold URL redaction, body projection, fetch, XHR, SSE,
- * WebSocket and sendBeacon at once. This module owns exactly one question: given a body, what is safe
- * and affordable to report?
- */
 import { REDACTED_VALUE } from '@reticlehq/core';
 import { isSensitiveKey, safeStringify, scrubKnownSecrets } from '../security/serialization.js';
 import { nativeClearTimeout, nativeSetTimeout } from '../timers/native-timers.js';
-/** Only text-like bodies are worth capturing; binary (images/fonts/octet-stream) is skipped. */
 const CAPTURABLE_CONTENT = /application\/json|text\/|application\/xml|x-www-form-urlencoded|graphql/i;
-/**
- * Content types that are STREAMS, never complete bodies.
- *
- * `text/event-stream` matches `text/` in CAPTURABLE_CONTENT, and body capture awaited
- * `res.clone.text` BEFORE returning the response to the app. A clone of a stream only settles when
- * the stream ends — and an SSE stream does not end — so the app's `await fetch...)` never resolved.
- * Enabling body capture silently hung every streaming endpoint (SSE, and the chunked `application/json`
- * every token-streaming model API uses), leaving a permanently loading UI with no reason to suspect the
- * observability SDK. Never read these; the frame observer covers SSE properly.
- */
 const STREAMING_CONTENT = /event-stream|x-ndjson|application\/stream/i;
-/**
- * Content types that stay OPEN by design — watching them would make every first settle pay the full
- * watch bound for a stream doing exactly its job. Real SSE is covered by the EventSource observer.
- */
 const ENDLESS_BY_DESIGN = /event-stream/i;
-/**
- * Is this response body still arriving after the request itself resolved?
- *
- * STRUCTURAL, not a content-type allowlist. The first version listed `x-component|x-ndjson|
- * application/stream` — which is to say "Next.js RSC, plus two guesses". It closed the exact defect
- * it was written against and left every other streamed response as invisible as before: a chunked
- * `application/json` from a token API, a streamed HTML document, an export assembled server-side.
- * Fixing one app's symptom and calling the class solved is how a false green comes back wearing
- * different clothes.
- *
- * The real signal is on the wire: a response with a BODY and no `content-length` is being sent
- * chunked, which is the definition of "the server is still writing". `content-length` present means
- * the size was known up front and the body cannot grow.
- *
- * Deliberately independent of content type, with one exception above for streams that never end.
- */
 export function isStreamingBody(contentType, contentLength) {
     if (contentType !== null && ENDLESS_BY_DESIGN.test(contentType))
         return false;
     return null === contentLength;
 }
-/**
- * Longest the SDK will wait on a response-body clone before emitting without it.
- *
- * Two layers protect the app. `text/event-stream` and friends are skipped outright, which covers the
- * common streaming case at zero cost. This deadline is the backstop for a body that streams WITHOUT
- * announcing it in its content type — chunked `application/json` from a token-streaming API. Gating on
- * `content-length` instead was tried and rejected: plenty of complete responses omit it (gzip, HTTP/2),
- * so that would silently stop capturing bodies for ordinary apps. A bounded half-second on a rare path
- * beats an unbounded hang, and beats losing capture everywhere.
- */
 const BODY_READ_TIMEOUT_MS = 500;
-/**
- * Resolve with the body text, or `undefined` if it takes too long.
- *
- * The app is already awaiting our patched fetch, so any unbounded read here is a hang in the host app.
- * Losing an observation is always preferable to freezing the page being observed.
- */
 export async function withBodyDeadline(read) {
-    // The timer is CLEARED on the winning path. Left uncleared, every captured body leaves a live timer
-    // and a retained closure behind — harmless individually, but `boundedFrame` in this same package
-    // already races-with-cleanup correctly, so not reusing that shape was an oversight rather than a
-    // choice. It also keeps test workers from being held open by pending handles.
     let timer;
     try {
         return await Promise.race([
@@ -90,79 +32,40 @@ export function isCapturableType(contentType) {
         return false;
     return CAPTURABLE_CONTENT.test(contentType);
 }
-/**
- * Per-body character cap. Bodies ride the same ring buffer as the DOM/route/console timeline, so an
- * uncapped body could evict the whole behavioral history; the small cap keeps a few large responses
- * from starving the timeline (the separate-budget concern in the scalability audit).
- */
 const MAX_BODY_CHARS = 8192;
-/**
- * Hard bound on how much of a body is ever PARSED or SCANNED, independent of how much is reported.
- *
- * Only twice the output cap, and that ceiling is measured rather than guessed. The redaction pass uses
- * `[A-Za-z0-9_.-]+` followed by a delimiter, which backtracks quadratically on a long run without one.
- * Timed on this machine: 8 KB → 36 ms, 16 KB → 136 ms, 64 KB → 2067 ms. A first attempt at 8× the
- * output cap therefore still froze the main thread for seconds, so the bound is set where the cost
- * stays bounded AND redaction keeps enough context to catch a secret straddling the reported edge.
- * Scanning far past the output cap is wasted work in any case — only 8 KB is ever reported.
- */
 const MAX_BODY_SCAN_CHARS = MAX_BODY_CHARS * 2;
-/**
- * An `Authorization: Bearer …` / `Basic …` credential. The token side requires credential shape — 16+
- * chars AND at least one digit or symbol — so ordinary prose ("Basic subscription includes…", "Bearer
- * capacity exceeded") is NOT mangled, only actual opaque tokens are.
- */
 const AUTH_SCHEME_TOKEN = /\b(Bearer|Basic)\s+(?=[A-Za-z0-9._~+/=-]{16,})(?=[A-Za-z0-9._~+/=-]*[\d._~+/=-])[A-Za-z0-9._~+/=-]+/gi;
-/**
- * Redact credentials in ANY text body (form-urlencoded, text/plain, xml, or JSON that failed to parse).
- * sanitizeForTransport only redacts KEYS inside a parsed object, so a `password=secret` form post or a
- * `Bearer <token>` string would otherwise ship verbatim. Redacts the value of any `key=value` / `key: value`
- * pair whose key is sensitive, plus credential-shaped auth-scheme tokens.
- */
 function redactText(text) {
     return (text
-        // Auth-scheme tokens FIRST: `Authorization: Bearer <token>` — the key/value rule below would
-        // otherwise consume just "Bearer" as Authorization's value (it stops at whitespace) and leave the
-        // token behind, so the scheme rule must run before it.
         .replace(AUTH_SCHEME_TOKEN, (_m, scheme) => `${scheme} ${REDACTED_VALUE}`)
         .replace(/([A-Za-z0-9_.-]+)(\s*[=:]\s*"?)([^&\s,;"}]+)/g, (match, key, sep) => isSensitiveKey(key) ? `${key}${sep}${REDACTED_VALUE}` : match));
 }
-/**
- * Redact + cap a body for the agent transcript. JSON is parsed and run through the same
- * sanitizeForTransport redaction used for state (sensitive keys -> [REDACTED]); every other text body
- * (and JSON that didn't parse) goes through redactText so form/plain-text credentials can't leak.
- * Returns the (possibly truncated) body plus whether it was cut.
- */
+const ERROR_BODY_CHARS = 4096;
+export function shouldCaptureErrorBody(status, enabled) {
+    return enabled && status >= 400;
+}
+export function projectErrorBody(rawText, contentType) {
+    const projected = projectBody(rawText, contentType);
+    if (projected.body.length <= ERROR_BODY_CHARS)
+        return projected;
+    return { body: projected.body.slice(0, ERROR_BODY_CHARS), truncated: true };
+}
 export function projectBody(rawText, contentType) {
-    // Bound the INPUT before any parsing or scanning. The cap used to be applied only at the end, so a
-    // large body was JSON.parsed in full, deep-walked, re-stringified, and swept by two global regexes
-    // before all but 8 KB of the result was thrown away — seconds of synchronous main-thread work for a
-    // fixed-size output. A 30 MB CSV export or a big HTML error page froze the app, which is the same
-    // class of host-app damage as the streaming hang, with the SDK still the cause.
-    //
-    // The slice is generous (a multiple of the output cap) so redaction still sees enough context to
-    // recognise a secret that straddles the boundary, while the work stays bounded regardless of body size.
     const oversized = rawText.length > MAX_BODY_SCAN_CHARS;
     const text = oversized ? rawText.slice(0, MAX_BODY_SCAN_CHARS) : rawText;
     let out;
     if (contentType !== null && /json|graphql/i.test(contentType)) {
         try {
-            // safeStringify already sanitizes internally — the extra sanitizeForTransport here re-walked
-            // every captured JSON body a second time (~21% of the per-response cost) for an identical result.
             out = safeStringify(JSON.parse(text));
         }
         catch {
-            out = redactText(text); // looked like JSON but wasn't — still redact key/value + auth tokens
+            out = redactText(text);
         }
     }
     else {
         out = redactText(text);
     }
-    // Key-based redaction can't see a secret sitting in a VALUE under a benign key — scan the projected
-    // text for high-confidence secret shapes (JWTs, provider keys) as a backstop, JSON or not.
     out = scrubKnownSecrets(out);
-    // Truncated if the projection overflows the cap OR the input itself was clipped above — a body the
-    // SDK never fully read must not be reported as complete.
     const truncated = oversized || out.length > MAX_BODY_CHARS;
     return { body: out.length > MAX_BODY_CHARS ? out.slice(0, MAX_BODY_CHARS) : out, truncated };
 }

package/dist/observers/network-redact.d.ts

@@ -1,20 +1 @@
-/**
- * Redact credential-bearing values so they don't leak into the agent transcript / flow / run
- * artifacts: query params (`?access_token=…`, signed-URL keys) via the shared `isSensitiveKey` regex,
- * AND path-embedded tokens (`/reset/<token>`, `/invite/<token>`) that live in the path, not the query.
- * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
- */
-export declare function redactUrl(raw: string): string;
-/**
- * Displayed URL plus, when redaction rewrote it, the raw request for graders.
- *
- * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
- * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
- * changed, so an ordinary request pays nothing.
- */
-export declare function netUrlFields(raw: string): {
-    url: string;
-} | {
-    url: string;
-    urlRaw: string;
-};
+export { netUrlFields, redactUrl } from '@reticlehq/core';

package/dist/observers/network-redact.js

@@ -1,80 +1 @@
-import { REDACTED_VALUE, URL_RAW } from '@reticlehq/core';
-import { isSensitiveKey } from '../security/serialization.js';
-/** A path segment name that is typically followed by a single-use secret token in the NEXT segment. */
-const SENSITIVE_PATH_SEGMENT = /^(reset|verify|verification|confirm|activate|invite|magic|magiclink|token|key|oauth|unsubscribe|password)$/i;
-/** Only mask a following segment that looks token-like — short ids/words (`reset/form`) are left alone. */
-const PATH_TOKEN_MIN_LENGTH = 12;
-/**
- * Redact credential-bearing values so they don't leak into the agent transcript / flow / run
- * artifacts: query params (`?access_token=…`, signed-URL keys) via the shared `isSensitiveKey` regex,
- * AND path-embedded tokens (`/reset/<token>`, `/invite/<token>`) that live in the path, not the query.
- * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
- */
-export function redactUrl(raw) {
-    const hashStart = raw.indexOf('#');
-    const hash = -1 === hashStart ? '' : raw.slice(hashStart);
-    const beforeHash = -1 === hashStart ? raw : raw.slice(0, hashStart);
-    const queryStart = beforeHash.indexOf('?');
-    const pathPart = -1 === queryStart ? beforeHash : beforeHash.slice(0, queryStart);
-    const query = -1 === queryStart ? '' : beforeHash.slice(queryStart + 1);
-    let changed = false;
-    // Credentials in the authority (`scheme://user:pass@host`) never belong in a transcript.
-    // Match to the LAST `@` before the path (`[^/]*@`, greedy), not the first — a password containing
-    // `@` (`user:p@ss@host`) otherwise left its tail (`ss@host`) in the clear.
-    let authority = pathPart;
-    const userinfo = /^([a-z][a-z0-9+.-]*:\/\/)[^/]*@/i.exec(pathPart);
-    if (userinfo !== null) {
-        authority = `${userinfo[1] ?? ''}${REDACTED_VALUE}@${pathPart.slice(userinfo[0].length)}`;
-        changed = true;
-    }
-    let newQuery = query;
-    if (query !== '') {
-        const params = new URLSearchParams(query);
-        let queryChanged = false;
-        for (const key of [...params.keys()]) {
-            if (isSensitiveKey(key)) {
-                params.set(key, REDACTED_VALUE);
-                queryChanged = true;
-            }
-        }
-        if (queryChanged) {
-            newQuery = params.toString();
-            changed = true;
-        }
-    }
-    const segments = authority.split('/');
-    for (let i = 0; i + 1 < segments.length; i++) {
-        const name = segments[i];
-        const next = segments[i + 1];
-        if (name !== undefined &&
-            next !== undefined &&
-            next.length >= PATH_TOKEN_MIN_LENGTH &&
-            SENSITIVE_PATH_SEGMENT.test(name)) {
-            segments[i + 1] = REDACTED_VALUE;
-            changed = true;
-        }
-    }
-    // OAuth implicit flow puts the access_token in the FRAGMENT (`#access_token=…`), and hash-routers carry
-    // `?token=…` in the hash — redact sensitive params there too, leaving plain anchors (`#section`) alone.
-    let newHash = hash;
-    if (hash.length > 1) {
-        newHash = hash.replace(/([A-Za-z0-9_.-]+)=([^&\s]+)/g, (m, key) => isSensitiveKey(key) ? `${key}=${REDACTED_VALUE}` : m);
-        if (newHash !== hash)
-            changed = true;
-    }
-    if (!changed)
-        return raw;
-    const queryOut = -1 === queryStart ? '' : `?${newQuery}`;
-    return `${segments.join('/')}${queryOut}${newHash}`;
-}
-/**
- * Displayed URL plus, when redaction rewrote it, the raw request for graders.
- *
- * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
- * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
- * changed, so an ordinary request pays nothing.
- */
-export function netUrlFields(raw) {
-    const url = redactUrl(raw);
-    return url === raw ? { url } : { url, [URL_RAW]: raw };
-}
+export { netUrlFields, redactUrl } from '@reticlehq/core';

package/dist/observers/network-stream.d.ts

@@ -1,23 +1,2 @@
 import type { Emit } from './types.js';
-/**
- * Watch a STREAMED response body to its end, so `settled` cannot pass while the server is still
- * writing.
- *
- * `fetch` resolves at HEADERS. On a Next.js App Router page the RSC payload's NET_REQUEST landed
- * 16 ms in, the shell rendered at 3013, and the Suspense boundary's rows arrived at 3902 — 889 ms
- * in which NOTHING was observed. Quiet is exactly what settle tests for, so it passed with the
- * fallback still on screen and zero rows rendered: a green on every streaming boundary.
- *
- * STRUCTURAL, not an allowlist: a response with a body and no `content-length` is being sent
- * chunked, which is the wire's own way of saying the server is still writing. An earlier version
- * gated on a content-type list containing `x-component` — "Next.js RSC, plus two guesses" — which
- * closed the one defect it was written against and left every other streamed response as invisible
- * as before. The clone is DRAINED as it arrives rather than buffered, so watching costs a second
- * read of bytes already in flight, not a second copy held in memory.
- *
- * BOUNDED both ways: an endless stream (SSE over fetch, a live feed) must not hold `settled` open
- * forever, so the watch gives up after STREAM_WATCH_MS and closes the record anyway, marked
- * `gaveUp`. That is the safe direction — a settle that eventually proceeds beats one that never
- * does — and it says which happened rather than pretending the stream ended.
- */
 export declare function watchStreamedBody(emit: Emit, res: Response, id: string, url: string, contentType: string | null, contentLength: string | null): void;

package/dist/observers/network-stream.js

@@ -1,46 +1,8 @@
-/**
- * Watching a STREAMED response body to its end, so `settled` cannot pass mid-stream.
- *
- * Split out of network.ts, which was already at its line cap. One question: when did this response
- * actually finish arriving?
- */
 import { EventType, StreamDirection, StreamTransport } from '@reticlehq/core';
 import { isStreamingBody } from './network-body.js';
 import { nativeClearTimeout, nativeSetTimeout } from '../timers/native-timers.js';
-/**
- * Longest a streamed response body is watched before the record is closed anyway.
- *
- * An endless stream must never hold `settled` open forever. Ten seconds is longer than any
- * page-render stream and short enough that a genuinely endless one costs one settle window, not the
- * session.
- */
 const STREAM_WATCH_MS = 10_000;
-/**
- * Watch a STREAMED response body to its end, so `settled` cannot pass while the server is still
- * writing.
- *
- * `fetch` resolves at HEADERS. On a Next.js App Router page the RSC payload's NET_REQUEST landed
- * 16 ms in, the shell rendered at 3013, and the Suspense boundary's rows arrived at 3902 — 889 ms
- * in which NOTHING was observed. Quiet is exactly what settle tests for, so it passed with the
- * fallback still on screen and zero rows rendered: a green on every streaming boundary.
- *
- * STRUCTURAL, not an allowlist: a response with a body and no `content-length` is being sent
- * chunked, which is the wire's own way of saying the server is still writing. An earlier version
- * gated on a content-type list containing `x-component` — "Next.js RSC, plus two guesses" — which
- * closed the one defect it was written against and left every other streamed response as invisible
- * as before. The clone is DRAINED as it arrives rather than buffered, so watching costs a second
- * read of bytes already in flight, not a second copy held in memory.
- *
- * BOUNDED both ways: an endless stream (SSE over fetch, a live feed) must not hold `settled` open
- * forever, so the watch gives up after STREAM_WATCH_MS and closes the record anyway, marked
- * `gaveUp`. That is the safe direction — a settle that eventually proceeds beats one that never
- * does — and it says which happened rather than pretending the stream ended.
- */
 export function watchStreamedBody(emit, res, id, url, contentType, contentLength) {
-    // `=== null` is not enough: jsdom's Response has no `body` at all, and older/polyfilled
-    // implementations return undefined. Reaching for `.getReader()` on that threw an unhandled
-    // rejection out of a detached promise — an observability layer throwing into the host page, from
-    // code the host never called. Duck-type the reader instead of trusting the shape.
     if (!isStreamingBody(contentType, contentLength))
         return;
     if (typeof res.body?.getReader !== 'function')
@@ -50,7 +12,7 @@ export function watchStreamedBody(emit, res, id, url, contentType, contentLength
         clone = res.clone();
     }
     catch {
-        return; // already consumed or locked — the app owns it; observing it would take it away
+        return;
     }
     const body = clone.body;
     if (null === body)
@@ -64,10 +26,6 @@ export function watchStreamedBody(emit, res, id, url, contentType, contentLength
     void (async () => {
         const reader = body.getReader();
         let gaveUp = false;
-        // The deadline must be a TIMER, not a check after each read. An idle stream parks inside
-        // `read()` waiting for a chunk that may never come, so a post-read check never runs and the
-        // record never closes — which would hold `settled` open forever on exactly the endless streams
-        // the bound exists to protect against.
         let timer;
         const expired = new Promise((resolve) => {
             timer = nativeSetTimeout(() => resolve('expired'), STREAM_WATCH_MS);
@@ -85,7 +43,6 @@ export function watchStreamedBody(emit, res, id, url, contentType, contentLength
             }
         }
         catch {
-            /* aborted or errored — the stream is over either way, which is what we report */
         }
         finally {
             if (timer !== undefined)

package/dist/observers/network.d.ts

@@ -1,41 +1,17 @@
-import type { Emit, Teardown } from './types.js';
+import { type Emit, type Teardown } from './types.js';
 import { redactUrl, netUrlFields } from './network-redact.js';
 export { redactUrl, netUrlFields };
-/** Config for the network observer. Body capture is OFF by default and dev-only opt-in. */
-/**
- * Reinterpret a completed request's fields from its response.
- *
- * The seam exists so this observer stays ignorant of desktop IPC. A Tauri `invoke` arrives here as an
- * ordinary fetch to an `ipc://` protocol, and the header that says whether the Rust command
- * succeeded means nothing to a network observer — so the knowledge lives in the IPC observer and is
- * passed IN, rather than this module importing it. Returns undefined to leave the record untouched.
- */
 type NetResponseReinterpreter = (url: string, header: (name: string) => string | null) => Record<string, unknown> | undefined;
 interface NetworkOptions {
-    /** Capture request/response bodies (text-like content only, redacted, per-body capped). */
     captureBodies?: boolean;
-    /** Optional hook that reinterprets a completed request — see NetResponseReinterpreter. */
+    captureErrorBodies?: boolean;
     reinterpret?: NetResponseReinterpreter;
-    /**
-     * Requests Reticle itself makes, which must never reach the app's evidence.
-     *
-     * Same seam and same reason as `reinterpret`: this observer knows nothing about desktop IPC, and
-     * the SDK's own Tauri screenshot travels as an ordinary fetch through this very patch. Passed in
-     * rather than imported, so the knowledge stays in the IPC observer.
-     */
     ignore?: (url: string) => boolean;
 }
-/** Pure: the first real app-code frame in a stack string, capped. Exported for unit testing. */
 export declare function firstAppFrame(stack: string | undefined): string | undefined;
-/** The timing fields we lift from a resource entry — TTFB is the perf signal a duration alone hides. */
 interface NetTiming {
     ttfbMs?: number;
     transferSize?: number;
 }
-/**
- * Pure: derive TTFB + transfer size from a PerformanceResourceTiming entry. TTFB = responseStart -
- * requestStart; cross-origin responses zero those (Timing-Allow-Origin), so we omit rather than report a
- * bogus 0. Exported for unit testing (jsdom doesn't post real resource entries).
- */
 export declare function extractTiming(entry: PerformanceResourceTiming | undefined): NetTiming;
 export declare function installNetwork(emit: Emit, opts?: NetworkOptions): Teardown;