Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(witness): let a page opt a handled 5xx out of the unhandled-failure count

nirholasc35db863601c
diff --git a/packages/witness/src/recorder.js b/packages/witness/src/recorder.js
index e91e3eee3..4baeaf3e2 100644
--- a/packages/witness/src/recorder.js
+++ b/packages/witness/src/recorder.js
@@ -42,6 +42,41 @@ const DEFAULTS = {
sampleScrolls: false,
};
+// Header a caller sets to say "I render a designed state for every status this
+// request can return". Its 5xx is then recorded as history but never counted as
+// an unhandled failure, so nothing proactively interrupts a page that is already
+// explaining what happened. Mirrors the DOM opt-out, data-witness="off".
+const HANDLED_HEADER = 'x-witness';
+const HANDLED_VALUE = 'handled';
+
+function headerValue(headers, name) {
+ if (!headers) return '';
+ try {
+ if (typeof headers.get === 'function') return String(headers.get(name) || '');
+ if (Array.isArray(headers)) {
+ const hit = headers.find((pair) => String(pair?.[0] ?? '').toLowerCase() === name);
+ return hit ? String(hit[1] ?? '') : '';
+ }
+ for (const key of Object.keys(headers)) {
+ if (key.toLowerCase() === name) return String(headers[key] ?? '');
+ }
+ } catch {
+ /* a malformed headers bag is simply not an opt-out */
+ }
+ return '';
+}
+
+function requestOptsOut(input, init) {
+ try {
+ const fromInit = headerValue(init?.headers, HANDLED_HEADER);
+ if (fromInit.toLowerCase() === HANDLED_VALUE) return true;
+ const fromRequest = typeof input === 'object' && input ? headerValue(input.headers, HANDLED_HEADER) : '';
+ return fromRequest.toLowerCase() === HANDLED_VALUE;
+ } catch {
+ return false;
+ }
+}
+
function now() {
return Date.now();
}
@@ -273,11 +308,21 @@ export class Recorder {
const method = String(init?.method || input?.method || 'GET').toUpperCase();
const raw = typeof input === 'string' ? input : input?.url || '';
const path = redactUrl(raw, { origin });
+ // A caller that ships `x-witness: handled` has a designed state for
+ // every status this request can answer with, so its 5xx is a product
+ // state, not an unhandled fault. The event is still recorded (a bug
+ // report should carry it), it just stops being the thing that makes
+ // the companion interrupt with "something just broke". The DOM
+ // sibling of this opt-out is data-witness="off".
+ const handled = requestOptsOut(input, init);
if (path && !self.options.ignore?.(path)) {
promise.then(
(res) => {
if (res && !res.ok) {
- self.record('xhr', { detail: `${method} ${path} -> ${res.status}`, fatal: res.status >= 500 || res.status === 0 });
+ self.record('xhr', {
+ detail: `${method} ${path} -> ${res.status}`,
+ fatal: !handled && (res.status >= 500 || res.status === 0),
+ });
}
},
(err) => {
diff --git a/tests/witness-handled-status.test.js b/tests/witness-handled-status.test.js
new file mode 100644
index 000000000..151a05248
--- /dev/null
+++ b/tests/witness-handled-status.test.js
@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+//
+// `x-witness: handled` on a request (packages/witness/src/recorder.js), and the
+// reason /forge sends it on every /api/forge call.
+//
+// A page that renders a designed state for a status is not experiencing an
+// unhandled failure. Without this opt-out the recorder counted every designed
+// 503 from the generator (storage down, free lane unavailable) as a fatal
+// event, which is what the feedback companion reads to decide whether to
+// interrupt with "something just broke, want to report it?" — an offer that at
+// 320px landed directly on top of the Try again button the error state was
+// showing.
+//
+// The event is still recorded either way. Only `fatal` changes, so a bug report
+// the user does choose to file still carries the call.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Recorder } from '../packages/witness/src/recorder.js';
+
+let recorder;
+
+function startRecorder() {
+ recorder = new Recorder({ captureNetwork: true });
+ recorder.install();
+}
+
+describe('witness handled-status opt-out', () => {
+ beforeEach(() => {
+ window.fetch = vi.fn(async () => new Response('{}', { status: 503 }));
+ });
+
+ afterEach(() => {
+ recorder?.uninstall();
+ recorder = null;
+ });
+
+ it('counts an unmarked 5xx as a failure worth interrupting for', async () => {
+ startRecorder();
+ await window.fetch('/api/forge', { method: 'POST' });
+ expect(recorder.hasFailure()).toBe(true);
+ });
+
+ it('records a marked 5xx but does not treat it as an unhandled failure', async () => {
+ startRecorder();
+ await window.fetch('/api/forge', { method: 'POST', headers: { 'x-witness': 'handled' } });
+ expect(recorder.hasFailure()).toBe(false);
+ expect(recorder.trace().events.some((e) => e.type === 'xhr' && e.detail.includes('503'))).toBe(true);
+ });
+
+ it('reads the marker from a Headers instance and ignores case', async () => {
+ startRecorder();
+ await window.fetch('/api/forge', { method: 'POST', headers: new Headers({ 'X-Witness': 'Handled' }) });
+ expect(recorder.hasFailure()).toBe(false);
+ });
+
+ it('reads the marker from a Request object', async () => {
+ startRecorder();
+ await window.fetch(new Request('http://localhost/api/forge', { headers: { 'x-witness': 'handled' } }));
+ expect(recorder.hasFailure()).toBe(false);
+ });
+
+ it('still counts a rejected request, marker or not', async () => {
+ window.fetch = vi.fn(async () => {
+ throw new Error('network error');
+ });
+ startRecorder();
+ await window.fetch('/api/forge', { headers: { 'x-witness': 'handled' } }).catch(() => {});
+ expect(recorder.hasFailure()).toBe(true);
+ });
+});