@agent-native/core 0.209.1 → 0.209.2-nightly-20261015213030

package/dist/server/loopback.js

@@ -16,3 +16,33 @@ export function isLoopbackRequest(event) {
     }
     return isLoopbackAddress(ip);
 }
+export function isDirectLoopbackRequest(event) {
+    const request = event.node?.req;
+    const headers = request?.headers;
+    const host = headers?.host;
+    const socket = request?.socket;
+    const hasForwardedHeader = Object.keys(headers ?? {}).some((name) => {
+        const normalizedName = name.toLowerCase();
+        return (normalizedName === "forwarded" ||
+            normalizedName.startsWith("x-forwarded-"));
+    });
+    if (!isLoopbackRequest(event) ||
+        typeof host !== "string" ||
+        !/^127\.0\.0\.1(?::\d{1,5})?$/.test(host) ||
+        hasForwardedHeader ||
+        !socket ||
+        ("encrypted" in socket && socket.encrypted) ||
+        (socket.localAddress !== "127.0.0.1" &&
+            socket.localAddress !== "::ffff:127.0.0.1")) {
+        return false;
+    }
+    const originValue = `http://${host}`;
+    if (!URL.canParse(originValue))
+        return false;
+    const origin = new URL(originValue);
+    return (origin.hostname === "127.0.0.1" &&
+        origin.port !== "0" &&
+        origin.pathname === "/" &&
+        origin.search === "" &&
+        origin.hash === "");
+}

package/dist/server/origin-allowlist.d.ts

@@ -7,4 +7,6 @@ export declare function firstOriginFromEnv(keys: readonly string[], options: {
     allowLoopback: boolean;
 }): string | undefined;
 export declare function getConfiguredOriginAllowlist(): Set<string>;
+/** The allowlist minus platform-assigned origins, in declaration order. */
+export declare function getAppDeclaredOrigins(): string[];
 export declare function requestForwardedOrigin(request: Request | undefined): string | undefined;

package/dist/server/origin-allowlist.js

@@ -72,9 +72,14 @@ export function firstOriginFromEnv(keys, options) {
     }
     return undefined;
 }
-export function getConfiguredOriginAllowlist() {
+// Netlify fills these with its own hostnames. A site served through a proxy
+// (Builder Cloud) is never browsed at them, so they do not declare where the app lives.
+const PLATFORM_ORIGIN_ENV_KEYS = new Set(["URL", "DEPLOY_URL"]);
+function collectConfiguredOrigins(options) {
     const out = new Set();
     for (const key of EXPLICIT_PUBLIC_ORIGIN_ENV_KEYS) {
+        if (!options.includePlatform && PLATFORM_ORIGIN_ENV_KEYS.has(key))
+            continue;
         addNormalizedOrigin(out, process.env[key], { allowLoopback: true });
     }
     for (const origin of (process.env[BETTER_AUTH_TRUSTED_ORIGINS_ENV_KEY] ?? "").split(",")) {
@@ -85,6 +90,13 @@ export function getConfiguredOriginAllowlist() {
     }
     return out;
 }
+export function getConfiguredOriginAllowlist() {
+    return collectConfiguredOrigins({ includePlatform: true });
+}
+/** The allowlist minus platform-assigned origins, in declaration order. */
+export function getAppDeclaredOrigins() {
+    return [...collectConfiguredOrigins({ includePlatform: false })];
+}
 export function requestForwardedOrigin(request) {
     if (!request)
         return undefined;

package/dist/server/realtime-token.d.ts

@@ -54,8 +54,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/server/request-context.d.ts

@@ -77,6 +77,8 @@ export interface RequestContext {
     userName?: string;
     orgId?: string;
     orgScope?: "personal";
+    /** Explicitly selects deployment-wide agent defaults for shared no-org jobs. */
+    defaultAgentEngineScope?: "deployment";
     /**
      * Narrow authorization capability verified from an embed session. This is
      * deliberately separate from user identity: capability-only sessions must
@@ -113,6 +115,8 @@ export interface RequestContext {
      * radius (a resource that is itself local-only, NODE_ENV, etc.).
      */
     isLoopbackRequest?: boolean;
+    /** True only when this server received the request directly on 127.0.0.1. */
+    isDirectLoopbackRequest?: boolean;
     isIntegrationCaller?: boolean;
     integration?: {
         taskId: string;

package/dist/templates/chat/app/components/layout/Sidebar.tsx

@@ -5,6 +5,7 @@ import {
   useChatThreads,
   type ChatThreadSummary,
 } from "@agent-native/toolkit/app/chat/agentkit-chat/rail";
+import { ReportProblemButton } from "@agent-native/toolkit/app/feedback";
 import { OrgSwitcher } from "@agent-native/toolkit/app/org";
 import { openCommandMenu } from "@agent-native/toolkit/app/shared";
 import { AgentNativeIcon } from "@agent-native/toolkit/app/shared/AgentNativeIcon";
@@ -567,7 +568,16 @@ export function Sidebar({
         <ChatThreadsSection collapsed={collapsed} />
       </nav>
 
-      <div className="mt-auto shrink-0 border-t border-sidebar-border p-2">
+      <div
+        className={cn(
+          "mt-auto shrink-0 px-2 pb-1",
+          collapsed && "flex justify-center",
+        )}
+      >
+        <ReportProblemButton variant={collapsed ? "icon" : "sidebar"} />
+      </div>
+
+      <div className="shrink-0 border-t border-sidebar-border p-2">
         <div
           className={cn(
             collapsed

package/dist/templates/factory/.agents/skills/review-latest-feedback/SKILL.md

@@ -126,8 +126,8 @@ record source, target, owner, exact action, and verification. Don't reopen
 closed fixes.
 **Clustered** closes one row but retains it.
 
-Enumerate channel parents newest backward through `next_cursor` until older
-than 5 days. Check reactions first; skip marked messages.
+Enumerate channel parents newest-first for five days. For a permalink plus
+newer scope, follow the [checked inventory procedure](references/channel-inventory.md).
 
 **`slack_search` can rank and truncate.** Use channel reads to enumerate parents
 and put their count in the recap. Sort targeted searches oldest-first and follow

package/dist/templates/factory/.agents/skills/review-latest-feedback/references/channel-inventory.md

@@ -0,0 +1,31 @@
+# Channel parent inventory
+
+Use this procedure before investigating, claiming, or using a CI rollup in
+place of Slack source messages.
+
+- Read each scoped channel newest-first, following `next_cursor` until the
+  five-day boundary, the inclusive permalink cutoff, or Slack exhaustion.
+- For “this permalink and newer,” use the parent message's `ts` as the inclusive
+  `cutoffTs` and `permalinkTs`. Slack's `oldest` parameter is exclusive, so
+  query from at least one second earlier and filter locally by `ts >= cutoff`.
+- Record every top-level parent returned in every fetched page before filtering
+  or triage. This includes duplicates, owned items, bots, and boundary overlap.
+  Reactions and ownership determine what to investigate, not what to inventory.
+- Save `.tmp/feedback-inventory.json` with `cutoffTs`, optional `permalinkTs`,
+  and `channels`. Set `permalinkTs` when a supplied message anchors the scan. A channel
+  has `channelId`, `oldestQuery`, and `pages`. A page has its requested `cursor`,
+  returned `nextCursor`, `exhausted`, the full Slack `parentCount`, the complete
+  `sourceTimestamps` list copied from that response, and `parents`. Each parent
+  records `ts`, `reactionChecked: true`, `reactionSummary` (`none` if empty),
+  and `disposition`.
+- Keep the source manifest separate from disposition rows. Copy every timestamp
+  and the count from the full Slack response before filtering; the checker
+  compares both lists, catches missing parents and requires the requested
+  permalink timestamp to appear. Continue until a fetched page contains a
+  parent older than cutoff or Slack reports exhaustion.
+- Run `pnpm feedback:inventory-check -- .tmp/feedback-inventory.json`. It checks
+  boundary overlap, page/cursor order, count parity, timestamps, reaction state,
+  and dispositions. Include each channel's parent and page counts in the recap.
+
+A grouped CI report or attachment is a discovery index, never a replacement for
+the channel-parent inventory.

package/dist/triggers/dispatcher.js

@@ -3,7 +3,7 @@ import { isProductionServerlessFunctionRuntime } from "../db/client.js";
 import { subscribeAll, unsubscribe } from "../event-bus/index.js";
 import { countAutomationCredentialState, trackAutomationPaused, } from "../jobs/automation-events.js";
 import { applyAutomationFailure, classifyAutomationFailure, CLEAR_FAILURE_STATE, CONFIG_INVALID_ERROR_CODE, OWNER_MISSING_ERROR_CODE, pauseNow, } from "../jobs/automation-outcome.js";
-import { BackgroundAutomationRunError, checkBackgroundAutomationCredentials, isBackgroundAutomationRunActive, runBackgroundAutomation, } from "../jobs/background-automation-runner.js";
+import { BackgroundAutomationRunError, checkBackgroundAutomationCredentials, isBackgroundAutomationRunActive, runBackgroundAutomation, validateAutomationRunIdentity, } from "../jobs/background-automation-runner.js";
 import { buildJobResourceContent, jobBelongsToApp, parseJobResource, patchJobFrontmatterFields, } from "../jobs/frontmatter.js";
 import { registerRecurringSweepHandler, } from "../jobs/sweep-hooks.js";
 import { resourceFingerprintAllOwners, resourceGetByPath, resourceListAllOwnersWithFingerprint, resourcePutIfCurrent, } from "../resources/store.js";
@@ -853,12 +853,54 @@ async function dispatchQueuedAutomationEvent(queued, deps, hardDeadlineAt) {
         return "retry";
     let identity;
     if (resource.owner === "__shared__") {
-        const userEmail = meta.createdBy || resource.owner;
+        const userEmail = meta.createdBy?.trim().toLowerCase();
+        if (!userEmail) {
+            await recordTriggerExecutionOutcome(resource, { lastCheck: new Date().toISOString() }, {
+                failure: {
+                    code: CONFIG_INVALID_ERROR_CODE,
+                    message: "Shared automation has no creator identity.",
+                    precondition: true,
+                },
+                pauseImmediately: true,
+                eventId: queued.eventId,
+            });
+            return "completed";
+        }
+        const orgId = meta.orgId?.trim() || undefined;
+        let validation;
+        try {
+            validation = await validateAutomationRunIdentity(userEmail, orgId);
+        }
+        catch (error) {
+            await recordTriggerSkip(resource, "error", "Could not verify the automation execution identity.", "owner_unverifiable");
+            throw error;
+        }
+        if (!validation.ok) {
+            if (validation.code === OWNER_MISSING_ERROR_CODE ||
+                validation.code === CONFIG_INVALID_ERROR_CODE) {
+                await recordTriggerExecutionOutcome(resource, { lastCheck: new Date().toISOString() }, {
+                    failure: {
+                        code: validation.code,
+                        message: validation.reason,
+                        precondition: true,
+                    },
+                    pauseImmediately: true,
+                    eventId: queued.eventId,
+                });
+                return "completed";
+            }
+            await recordTriggerSkip(resource, "error", validation.reason, validation.code);
+            return "completed";
+        }
         identity = {
             userEmail,
-            orgId: meta.orgId,
+            orgId,
+            ...(!orgId ? { defaultAgentEngineScope: "deployment" } : {}),
             eventOwner: userEmail.toLowerCase(),
         };
+        if (!automationMatchesEventOwner(identity, queued.eventOwner)) {
+            return "completed";
+        }
     }
     else {
         let resolved;
@@ -900,7 +942,16 @@ async function dispatchQueuedAutomationEvent(queued, deps, hardDeadlineAt) {
     let classifierEngine;
     let classifierModel;
     if (meta.condition?.trim()) {
-        const credentialCheck = await checkBackgroundAutomationCredentials({ ownerEmail: identity.userEmail, orgId: identity.orgId }, deps, meta.model);
+        const credentialCheck = await checkBackgroundAutomationCredentials({
+            ownerEmail: identity.userEmail,
+            orgId: identity.orgId,
+            ...(identity.orgScope === "personal"
+                ? { orgScope: "personal" }
+                : {}),
+            ...(identity.defaultAgentEngineScope === "deployment"
+                ? { defaultAgentEngineScope: "deployment" }
+                : {}),
+        }, deps, meta.model);
         if (!credentialCheck.ok) {
             await recordTriggerExecutionOutcome(resource, { lastCheck: new Date().toISOString() }, { failure: credentialCheck.failure });
             return "completed";
@@ -910,7 +961,16 @@ async function dispatchQueuedAutomationEvent(queued, deps, hardDeadlineAt) {
     }
     let matches;
     try {
-        matches = await runWithRequestContext({ userEmail: identity.userEmail, orgId: identity.orgId }, () => evaluateCondition(meta.condition, queued.payload, {
+        matches = await runWithRequestContext({
+            userEmail: identity.userEmail,
+            orgId: identity.orgId,
+            ...(identity.orgScope === "personal"
+                ? { orgScope: "personal" }
+                : {}),
+            ...(identity.defaultAgentEngineScope === "deployment"
+                ? { defaultAgentEngineScope: "deployment" }
+                : {}),
+        }, () => evaluateCondition(meta.condition, queued.payload, {
             userEmail: identity.userEmail,
             orgId: identity.orgId,
             appId: deps.appId,
@@ -979,7 +1039,16 @@ export async function dispatchAutomationWebhookTask(task) {
     let classifierEngine;
     let classifierModel;
     if (meta.condition?.trim()) {
-        const credentialCheck = await checkBackgroundAutomationCredentials({ ownerEmail: identity.userEmail, orgId: identity.orgId }, deps, meta.model);
+        const credentialCheck = await checkBackgroundAutomationCredentials({
+            ownerEmail: identity.userEmail,
+            orgId: identity.orgId,
+            ...(identity.orgScope === "personal"
+                ? { orgScope: "personal" }
+                : {}),
+            ...(identity.defaultAgentEngineScope === "deployment"
+                ? { defaultAgentEngineScope: "deployment" }
+                : {}),
+        }, deps, meta.model);
         if (!credentialCheck.ok) {
             throw new BackgroundAutomationRunError(credentialCheck.failure.message, credentialCheck.failure.code);
         }
@@ -991,7 +1060,16 @@ export async function dispatchAutomationWebhookTask(task) {
     }
     let matches;
     try {
-        matches = await runWithRequestContext({ userEmail: identity.userEmail, orgId: identity.orgId }, () => evaluateCondition(meta.condition, task.payload, {
+        matches = await runWithRequestContext({
+            userEmail: identity.userEmail,
+            orgId: identity.orgId,
+            ...(identity.orgScope === "personal"
+                ? { orgScope: "personal" }
+                : {}),
+            ...(identity.defaultAgentEngineScope === "deployment"
+                ? { defaultAgentEngineScope: "deployment" }
+                : {}),
+        }, () => evaluateCondition(meta.condition, task.payload, {
             userEmail: identity.userEmail,
             orgId: identity.orgId,
             appId: deps.appId,
@@ -1083,32 +1161,40 @@ async function dispatchAgentic(resource, payload, eventMeta, identity, hardDeadl
         body: latestTrigger.body,
         resource: claimed,
     };
-    const requestContext = runningMeta.originScopeId &&
-        runningMeta.deliveryPlatform &&
-        runningMeta.deliveryDestination
-        ? {
-            isIntegrationCaller: true,
-            integration: {
-                taskId: `automation:${triggerName}:${eventMeta.eventId}`,
-                scopeId: runningMeta.originScopeId,
-                principalType: "service",
-                incoming: {
-                    platform: runningMeta.deliveryPlatform,
-                    externalThreadId: `${runningMeta.deliveryTenantId || "unknown"}:${runningMeta.deliveryDestination}:${runningMeta.deliveryThreadRef || "root"}`,
-                    text: "",
-                    tenantId: runningMeta.deliveryTenantId,
-                    integrationScopeId: runningMeta.originScopeId,
-                    platformContext: {
-                        channelId: runningMeta.deliveryDestination,
-                        threadTs: runningMeta.deliveryThreadRef,
-                        teamId: runningMeta.deliveryTenantId,
+    const requestContext = {
+        ...(identity.orgScope === "personal"
+            ? { orgScope: "personal" }
+            : {}),
+        ...(identity.defaultAgentEngineScope === "deployment"
+            ? { defaultAgentEngineScope: "deployment" }
+            : {}),
+        ...(runningMeta.originScopeId &&
+            runningMeta.deliveryPlatform &&
+            runningMeta.deliveryDestination
+            ? {
+                isIntegrationCaller: true,
+                integration: {
+                    taskId: `automation:${triggerName}:${eventMeta.eventId}`,
+                    scopeId: runningMeta.originScopeId,
+                    principalType: "service",
+                    incoming: {
+                        platform: runningMeta.deliveryPlatform,
+                        externalThreadId: `${runningMeta.deliveryTenantId || "unknown"}:${runningMeta.deliveryDestination}:${runningMeta.deliveryThreadRef || "root"}`,
+                        text: "",
+                        tenantId: runningMeta.deliveryTenantId,
+                        integrationScopeId: runningMeta.originScopeId,
+                        platformContext: {
+                            channelId: runningMeta.deliveryDestination,
+                            threadTs: runningMeta.deliveryThreadRef,
+                            teamId: runningMeta.deliveryTenantId,
+                        },
+                        threadRef: runningMeta.deliveryThreadRef,
+                        timestamp: now.getTime(),
                     },
-                    threadRef: runningMeta.deliveryThreadRef,
-                    timestamp: now.getTime(),
                 },
-            },
-        }
-        : undefined;
+            }
+            : {}),
+    };
     try {
         const result = await runBackgroundAutomation({
             automation,

package/docs/content/recorder.mdx

@@ -0,0 +1,259 @@
+---
+title: "Recorder"
+description: "The recorder is a short, redacted, in-memory record of what an app just did. It turns into a report for the app's agent, Clips, Sentry, or any destination you register."
+---
+
+# Recorder
+
+The recorder is a short, redacted, in-memory record of what an Agent-Native app just did. Every app records its actions, `application_state` writes, route changes, errors, and error toasts from the last two minutes, with no app code. When something goes wrong, that record becomes a report that the app's agent, a Clips recording, Sentry, or your own destination can read.
+
+```ts
+import { recorder } from "@agent-native/core/client/recorder";
+
+const report = recorder.report();
+```
+
+Nothing is stored on the server and nothing leaves the browser until a report is sent somewhere. The recorder makes no network requests of its own.
+
+## What it captures {#captured}
+
+| Type     | Source                                                                                                                    | Example                                                                                   |
+| -------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `action` | Every `useActionQuery()`, `useActionMutation()`, and `callAction()` call. Each action in a batched read is its own event. | `list-folders` failed with `403` and `forbidden_scope` inside a batch that returned `200` |
+| `state`  | Every `application_state` write and delete, including the ones that failed or were cancelled                              | `design-selection` changed `state` from `hover` to `focus`                                |
+| `nav`    | Route changes. Only the path is kept.                                                                                     | `/design/d_8f2c1a`                                                                        |
+| `error`  | Uncaught errors and unhandled promise rejections, with the first stack frame                                              | `TypeError` at `/app/pages/design-editor/commands/undo.ts:1715`                           |
+| `toast`  | Error and warning toasts the user saw                                                                                     | `This screen changed elsewhere. Your edit was not saved.`                                 |
+| `log`    | Events the app adds with `recorder.log()`                                                                                 | `screen.restored` from `f_1` to `f_9`                                                     |
+
+Each event has the same fields:
+
+| Field       | Meaning                                                                                          |
+| ----------- | ------------------------------------------------------------------------------------------------ |
+| `t`         | Seconds before the report was made. It is negative.                                              |
+| `at`        | Epoch milliseconds. Clips diagnostics use the same clock.                                        |
+| `type`      | `action`, `state`, `nav`, `error`, `toast`, or `log`                                             |
+| `name`      | The action name, state key, route path, error type, toast level, or log name                     |
+| `ok`        | Whether an action or state write succeeded                                                       |
+| `status`    | The HTTP status, when there was one                                                              |
+| `errorCode` | The action's error code. A call or write the app cancelled has `errorCode: "cancelled"`.         |
+| `ms`        | How long an action or state write took                                                           |
+| `requestId` | The server's request id, which also appears in its logs and in its Sentry event                  |
+| `data`      | Redacted, bounded details. An action has its HTTP method and, when it failed, its error message. |
+
+A state write records only what changed since the last value that key saved. The first write of a key records `data.value`. Later writes record `data.changed`, where a removed field reads `"[removed]"`. A write that changed nothing records `data.unchanged`, and a delete records `data.deleted`. A failed write also has `data.error`, and the next write is still compared with the last value that saved.
+
+## Reports {#reports}
+
+A report is the events in the window plus the values the app watches and the work still in flight.
+
+```json
+{
+  "app": "design",
+  "build": "59929e9",
+  "url": "/design/d_8f2c1a?file=[redacted]",
+  "at": "2026-10-14T16:20:05.120Z",
+  "reason": "user",
+  "windowSeconds": 120,
+  "events": [
+    {
+      "t": -12.4,
+      "at": 1791994792720,
+      "type": "state",
+      "name": "design-selection",
+      "ok": true,
+      "ms": 41,
+      "data": { "changed": { "state": "hover" } }
+    },
+    {
+      "t": -10.9,
+      "at": 1791994794220,
+      "type": "action",
+      "name": "update-file",
+      "ok": true,
+      "status": 200,
+      "ms": 180,
+      "requestId": "req_a1",
+      "data": { "method": "POST" }
+    }
+  ],
+  "watched": {
+    "inspector": {
+      "state": "focus",
+      "fields": [{ "label": "Opacity", "shown": "91%" }]
+    }
+  },
+  "pending": [],
+  "dropped": 0
+}
+```
+
+- **app**: the app id. Without one it falls back to the page's host, such as `localhost:8080`, so it is never empty.
+- **url**: the route path. Every query value is redacted and the hash is left out.
+- **windowSeconds**: how many seconds the report covers.
+- **pending**: actions and state writes still in flight, each with its `ageMs`.
+- **dropped**: events lost to the caps since the page loaded or the user signed out. Events that aged out of the window are not counted.
+
+## The SDK {#sdk}
+
+### `recorder.report()` {#report}
+
+`recorder.report()` returns the current report. It is synchronous. It accepts one optional object:
+
+- **seconds**: keep only the last `seconds` of the window.
+- **reason**: `"user"`, `"error"`, `"test"`, or `"manual"`. The default is `"manual"`.
+
+```ts
+const report = recorder.report();
+```
+
+Pass `seconds` for a shorter slice, such as the half minute before a recording started:
+
+```ts
+const before = recorder.report({ seconds: 30 });
+```
+
+Every reason except `"manual"` also sends the report to the `recorder.onReport()` listeners. A plain `recorder.report()` call never does, so a listener can build a report without looping.
+
+### `recorder.log()` {#log}
+
+`recorder.log()` adds an event in the app's own words. It accepts a name and optional data. Data that is not a plain object is recorded as `{ value }`.
+
+Design logs the new id of each screen that undo brings back, because undo re-creates deleted screens with new ids:
+
+```ts
+recorder.log("screen.restored", { from: file.id, to: result.id });
+```
+
+### `recorder.watch()` {#watch}
+
+`recorder.watch()` adds a live value to every report. It accepts a name and a function that returns the value, and it returns a function that stops watching.
+
+Design's inspector adds what it is showing and the interaction state it is editing. Neither is in `application_state`, so without this a report could not show them:
+
+```tsx
+useEffect(
+  () =>
+    recorder.watch("inspector", () => ({
+      state: interactionState ?? "default",
+      fields: readVisualScrubInputs(),
+    })),
+  [interactionState],
+);
+```
+
+A function that throws is reported as `{ unreadable: "<message>" }` rather than left out.
+
+### `recorder.onReport()` {#on-report}
+
+`recorder.onReport()` sends reports to a destination. It accepts a listener and returns a function that removes it. The listener receives every report built with a reason other than `"manual"`. That covers Report a problem (`"user"`), uncaught errors (`"error"`), and tests (`"test"`).
+
+```ts
+recorder.onReport((report) => posthog.capture("problem_report", report));
+```
+
+```ts
+recorder.onReport((report) =>
+  navigator.sendBeacon("/api/logs", JSON.stringify(report)),
+);
+```
+
+An uncaught error sends at most one report every ten seconds, so an error loop cannot flood a destination. A listener that throws is logged and the other listeners still run.
+
+### `recorder.redact()` {#redact}
+
+`recorder.redact()` hides more fields from every event recorded after the call and from every watched value. Pass field names, or dotted paths that start with the event's name. A `*` matches any one field.
+
+```ts
+recorder.redact("email");
+recorder.redact("compose.body", "payment.*");
+```
+
+### `recorder.pending()` {#pending}
+
+`recorder.pending()` lists the actions and state writes still in flight. Tests use it to wait for real idle instead of a fixed sleep. Design's end-to-end rails wait for it to be empty in `app.settled()`, and attach `recorder.json` to every failed test.
+
+```ts
+await expect
+  .poll(() =>
+    page.evaluate(
+      () => window.__agentNativeRecorder?.report({ seconds: 0 }).pending,
+    ),
+  )
+  .toEqual([]);
+```
+
+### `recorder.disable()` {#disable}
+
+`recorder.disable()` turns the recorder off. It does the same as `configureRecorder({ enabled: false })`.
+
+## `configureRecorder()` {#configure}
+
+`configureRecorder()` is one optional call. These are the defaults:
+
+```ts
+import { configureRecorder } from "@agent-native/core/client/recorder";
+
+configureRecorder({
+  windowSeconds: 120,
+  maxEvents: 2000,
+  sentry: true,
+  enabled: true,
+});
+```
+
+- **windowSeconds**: how far back the recorder keeps events.
+- **maxEvents**: the most events it keeps. When the cap is reached, the oldest events are dropped and counted in `dropped`.
+- **sentry**: whether Sentry errors get the recent events. It only acts when the app has browser Sentry.
+- **enabled**: whether the recorder runs at all.
+
+A window or cap that is not a positive number throws a `RangeError` instead of falling back to a default. The recorder also caps its total size at about 512 KB of JSON, whatever `maxEvents` is, which keeps it under 2 MB of memory per tab.
+
+## Destinations {#destinations}
+
+### Report a problem {#report-a-problem}
+
+Every app has **Report a problem**. It is at the bottom of the sidebar, in the agent panel's options menu, and in the command menu (⌘K).
+
+- It asks whether to attach what the app did in the last two minutes, and previews the counts, the failures, and the first events. It asks every time.
+- When the user agrees, the full report is stored as a private file that only that user can read. The app's agent receives a short summary with a reference to the file.
+- The agent reads more of the report with the `read-problem-report` action, filtered by event type or time.
+- When the page has no agent chat, the button copies the summary and the reference instead.
+- The report needs file storage. Without it, the dialog says the report was not attached, and nothing is sent.
+
+### Sentry {#sentry}
+
+When an app has browser Sentry configured through Agent-Native (see [Error reporting](/docs/observability#sentry)), every Sentry error event gets:
+
+- the last 100 events as breadcrumbs in the `recorder.action`, `recorder.state`, and similar categories, each with its outcome, status, and request id
+- the whole report as a `recorder.json` attachment
+
+This needs no app code. `configureRecorder({ sentry: false })` turns it off.
+
+### Your own destination {#own-destination}
+
+Register a listener with [`recorder.onReport()`](#on-report).
+
+### Clips and browser extensions {#extensions}
+
+The page exposes `window.__agentNativeRecorder.report()`. A browser extension reads it from the page's main world.
+
+When developer logs are on, the Clips extension reads it in the recorded tab when the recording starts (the last 30 seconds) and when it stops. The events join the recording's console and network entries on the same clock, and the clip's agent gets a summary of the failures. See [Clips browser logs](/docs/template-clips-features#chrome-extension-browser-logs).
+
+## Privacy {#privacy}
+
+- **It stays in the browser.** A report leaves only when a destination sends it: Report a problem after the user agrees, a Clips recording the user started, Sentry, or a listener the developer registered.
+- **Secrets are removed.** A field whose name looks secret (`password`, `token`, `secret`, `apiKey`, `authorization`, `cookie`, `session`, `card`, `cvv`) reads `"[redacted]"`. Token-looking text inside any value, such as JWTs, bearer tokens, and provider API keys, is replaced with `[redacted]` too. These are the same redactors core uses for error reports.
+- **Values are bounded.** Strings are cut at 200 characters and each event at about 2 KB. A cut says what it dropped. Request and response bodies are never recorded.
+- **It forgets.** It keeps only the window, up to its caps. It is cleared on reload and on sign-out.
+- **No new access.** The recorder only sees what already passes through the app. Action calls already go to the server, and `application_state` is already stored and read by the agent.
+
+## Turning it off {#off}
+
+```ts
+import { configureRecorder } from "@agent-native/core/client/recorder";
+
+configureRecorder({ enabled: false });
+```
+
+A disabled recorder forgets what it held, stops listening, and removes `window.__agentNativeRecorder` from the page. Its `recorder.report()` returns no events and no watched values, and it sends nothing to listeners. `configureRecorder({ enabled: true })` starts it again.