Files
PaperClipAI/doc/cloud-browser-analytics.md
T
DottaandClaude Opus 5.5 92dbf39e6f feat(analytics): attribute agent work and onboarding steps to a person on Cloud (#22260)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud sends product events straight to PostHog: server
events from `server/src/services/posthog-direct/` and browser events
from `ui/src/lib/analytics/`
> - A person-level funnel goes from sign-up to the first finished task
> - Agent-driven events (`agent.task_run`, `agent.task_completed`,
`agent.first_heartbeat`) used `workspace:<stackId>` as the distinct id,
so the funnel broke at those steps
> - The in-workspace onboarding wizard sent no step events, so we could
not see where people stop before their first agent
> - This pull request attributes agent work to the responsible person on
the Cloud direct path, and adds consent-gated onboarding step events in
the browser
> - The benefit is one PostHog person per customer across sign-up,
onboarding, agent runs, and task completion. Self-hosted output does not
change.

## Linked Issues or Issue Description

**Subsystem affected**
Cloud product analytics: Cloud direct PostHog delivery (server) and
browser product analytics (UI onboarding wizard).

**Problem or motivation**
A PostHog funnel from sign-up to the first finished task cannot follow
one person. Agent-driven events run in the background, with no signed-in
request, so they use the workspace id as the distinct id. The onboarding
wizard also sends no events, so we cannot see which step people leave.

**Proposed solution**
Give background emit sites a narrow scope that names the person
responsible for the work. Use the task creator first, then the task's
responsible user, then the run owner. Keep the signed-in request user
first. Add `attributed_via` to every Cloud direct event. Add four
browser events to the onboarding wizard. Send them through the existing
analytics module, so the consent rules stay the same.

**Alternatives considered**
A lookup in the transport at send time. We did not use it: it adds
database reads to the telemetry path and loses the emit site's context.
A new contract event for onboarding steps. We did not use it: the server
does not see the wizard steps, and the UI must never send
`PAPERCLIP_EVENTS` names.

**Additional context**
Self-hosted installs keep the collector path. The collector envelope
stays byte-identical (a test checks it).

## What Changed

- `server/src/telemetry-company-scope.ts`: add `withTelemetryActor({
companyId, person }, fn)`, `scopedTelemetryPerson()`, and
`resolveTelemetryPerson()`. The resolver picks the task creator, then
the task's responsible user, then the run owner. It ignores
`local-board`. `withTelemetryCompany` now calls `withTelemetryActor`.
- `server/src/services/posthog-direct/request-context.ts`: a signed-in
request user wins (`attributed_via: request`). Without one, the scoped
person is used.
- `server/src/services/posthog-direct/event-shape.ts`: every Cloud
direct event (including `cloud.workspace_started`) has `attributed_via`
(`request`, `task_creator`, `task_assigner`, `run_owner`, or `none`). An
event with a person keeps today's person-event shape (no
`$process_person_profile: false`).
- `server/src/services/agent-task-run-telemetry.ts`: `agent.task_run`
reads the task creator and responsible user in the existing agent query
(one left join, no new query), and the run's `responsibleUserId`.
- `server/src/routes/issues.ts`: `agent.task_completed` uses the issue
row that the route already has, and the agent actor's `onBehalfOfUserId`
as the run owner.
- `server/src/services/heartbeat/agent-status.ts`:
`agent.first_heartbeat` uses the agent's `createdByUserId` (already
loaded) as the run owner.
- `ui/src/lib/analytics/product-analytics.ts`: add
`captureProductAnalyticsEvent()`. It captures only with a browser
analytics config and granted consent. Events from before posthog-js
loads wait in a queue (at most 50) and keep their time. Withdrawn
consent or a change of signed-in person drops the queue.
- `ui/src/lib/analytics/onboarding-analytics.ts` and
`ui/src/components/OnboardingWizard.tsx`: capture `onboarding_opened`,
`onboarding_step_viewed`, `onboarding_step_completed` (with `step` and,
for `connect_model` and `launch`, `outcome`), and
`onboarding_dismissed`. `step` is `create_agent`, `connect_model`,
`review`, or `launch`. No event has free text.
- Docs: `packages/shared/src/telemetry/README.md` (Cloud Direct
Delivery) and `doc/cloud-browser-analytics.md` (new "Onboarding events"
section).

## Verification

- `server/src/__tests__/posthog-direct-telemetry.test.ts`: attribution
matrix (creator, assigner, run owner, none stays on
`workspace:<stackId>` with `$process_person_profile: false`), the
request user wins over the scope, and the self-hosted collector envelope
is byte-identical with a person scope.
- `server/src/__tests__/agent-task-run-telemetry.test.ts` (embedded
Postgres): `agent.task_run` scope for creator, assigner, run owner, and
nobody; another company's task is never read.
- `server/src/__tests__/issue-telemetry-routes.test.ts`:
`agent.task_completed` scope for creator and assigner.
- `server/src/__tests__/heartbeat-process-recovery.test.ts`:
`agent.first_heartbeat` scope is the agent owner.
- `ui/src/components/OnboardingWizard.test.tsx`: a launch for the old
company that settles after a switch to another company does not end the
new analytics session.
- `ui/src/lib/analytics/onboarding-analytics.test.tsx`: each transition
fires once, held events drop on a person change, a stale opening step is
not a view, dismissal fires once, nothing is captured when analytics is
off or consent is `denied` or `ask`, and queued events keep their time.
- `ui/src/lib/analytics/product-analytics-events.test.ts` still passes
(the UI never captures a `PAPERCLIP_EVENTS` name).
- Local Cloud-mode run: an isolated instance (own Postgres, trusted
Cloud tenant headers, `PAPERCLIP_POSTHOG_HOST` set to a local capture
server, never real PostHog). A stub stood in for posthog-js and sent
through the `/_ph` proxy.
- A user created a task and assigned it to the agent. `agent.task_run`
arrived with `distinct_id: paperclip-id:local-user-1`, `attributed_via:
task_creator`, the raw `task_id`, and no `$process_person_profile`. (The
run itself failed locally because the Cloud runner is not available. The
event still shows the attribution.)
- `agent.first_heartbeat` arrived with the same person and
`attributed_via: run_owner`. `server.started` kept
`workspace:stack-local` with `attributed_via: none`.
- Headless Chromium walked the wizard: `onboarding_opened`
(create_agent), `onboarding_step_viewed` (create_agent),
`onboarding_step_completed` (create_agent), `onboarding_step_viewed`
(connect_model), `onboarding_step_completed` (connect_model, `api_key`),
`onboarding_step_viewed` (review), `onboarding_step_completed` (review),
`onboarding_step_completed` (launch, `succeeded`). Each fired once, with
the signed-in user as the distinct id. Events from before posthog-js
loaded arrived with their original time.
- A second walk left the onboarding page on the connect step and sent
one `onboarding_dismissed` (connect_model).

## Risks

- Low risk for self-hosted: the collector path never reads the new
scope, and a test checks the envelope bytes.
- Cloud: agent events move from the workspace person to a real person.
Insights that count `workspace:` distinct ids for these events will
change. `attributed_via` lets a query filter or split them.
- `task_assigner` uses the task's responsible user. Paperclip does not
store who assigned a task, so this is the person who owns or delegated
the task.
- Privacy: the new data is Cloud-only and uses ids that Cloud events
already carry. No new free text, email, or name goes on an event.
**Privacy review requested** for the Cloud attribution change (per
`rules/data-paths.mdc`). The generated contract does not change:
`attributed_via` is a Cloud-only property, like `stack_id` and
`user_id`.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, headless browser).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 18:44:45 -06:00

372 lines
22 KiB
Markdown

# Cloud Browser Product Analytics
On Paperclip Cloud, the board UI can send page views, sessions, autocapture
clicks, heatmaps, Web Vitals and session replays to PostHog. Self-hosted
installs never do this: they do not download `posthog-js` and do not serve the
PostHog proxy.
## Who gets it
The server decides, in `server/src/services/cloud-posthog-browser.ts`. The
authenticated `GET /api/auth/get-session` response carries a
`browserAnalytics` object only when all of these hold:
1. The instance is cloud managed (`isCloudManagedInstance`).
2. `PAPERCLIP_POSTHOG_PROJECT_TOKEN` and `PAPERCLIP_CLOUD_STACK_ID` are set.
3. `PAPERCLIP_POSTHOG_BROWSER_ENABLED=1`.
Otherwise the field is `null`, and the browser loads nothing. When it is set,
the browser loads PostHog's browser script (`/_ph/static/array.js`, through the
proxy) only after the page settles (first paint, page reads finished, browser
idle), so cold loads do not wait for it. posthog-js is not an npm dependency
of the board and is in no bundle chunk; PostHog serves it, as it serves the
extensions posthog-js loads at run time (recorder, web vitals).
## Configuration
| Variable | Default | Meaning |
| --- | --- | --- |
| `PAPERCLIP_POSTHOG_PROJECT_TOKEN` | — | PostHog project token. It is public by design: it can send events but cannot read data. |
| `PAPERCLIP_POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog ingest host. The proxy forwards to it. |
| `PAPERCLIP_POSTHOG_ENVIRONMENT` | — | `staging` or `production`. Added to every event as `environment`. |
| `PAPERCLIP_POSTHOG_BROWSER_ENABLED` | off | `1` turns browser analytics on for this stack. Leave it unset to keep it off. |
| `PAPERCLIP_POSTHOG_REPLAY_ENABLED` | on (when browser analytics is on) | `0` turns session replay off for this stack and keeps the other browser analytics. |
| `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` | `1024` | Proxy requests in flight for the whole server. See [Proxy limits](#proxy-limits). |
| `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT` | `128` | Proxy requests in flight from one public client address. See [Proxy limits](#proxy-limits). |
| `PAPERCLIP_POSTHOG_COUNTRY_HEADER` | — | Name of a request header that the platform edge sets to the visitor's two-letter country code (for example `CF-IPCountry` behind a proxied Cloudflare zone). Leave it unset unless the edge sets the header and drops a value from the client. See [Consent](#consent). |
### Per-stack opt-out
For a customer whose contract forbids recording, set
`PAPERCLIP_POSTHOG_REPLAY_ENABLED=0` on that stack. To turn off all browser
analytics for a stack, unset `PAPERCLIP_POSTHOG_BROWSER_ENABLED`. Both take
effect on the next server restart.
## Consent
Visitors in the EU, the EEA, the UK and Switzerland must agree before browser
analytics and session replay start. Everyone else keeps analytics on by
default. Both can change the choice later. Server events are not affected:
they set no cookies.
### Who must agree
1. The server decides when it knows the visitor's country. If
`PAPERCLIP_POSTHOG_COUNTRY_HEADER` names a header and the request carries a
valid two-letter code in it, `browserAnalytics.consentRequired` is `true`
for the EU and EEA countries (and their outermost regions and Svalbard), the
UK (and the Crown Dependencies and Gibraltar) and Switzerland, and `false`
for every other ISO 3166-1 alpha-2 country. The aliases `UK` and `EL` count
as `GB` and `GR`, and `EU` and `EZ` count as consent required. Any other
value (for example `XX`, `UN`, `XK` or `T1`) gives `null`.
2. Otherwise `consentRequired` is `null`, and the browser decides from its time
zone. It asks when the zone starts with
`Europe/`, is an EU, EEA or UK zone outside Europe (for example
`Atlantic/Canary`, `Atlantic/Reykjavik`, `Asia/Nicosia`, `Indian/Reunion`),
or is unknown (`UTC`, `Etc/*`, empty, or `Intl` fails). When unsure, it asks.
Both lists live in one place, `packages/shared/src/analytics-consent.ts`
(`countryRequiresAnalyticsConsent`, `timeZoneRequiresAnalyticsConsent`). The
browser's choice logic is in `ui/src/lib/analytics/consent.ts`.
Paperclip Cloud uses the time zone today. Requests reach Railway through
DNS-only Cloudflare records, so no Cloudflare country header arrives, and the
Railway edge adds no country header. Set `PAPERCLIP_POSTHOG_COUNTRY_HEADER`
only when an edge that sets and overwrites a country header is in front of
the stack. A visitor who forges the header can only change the default for
their own browser.
### What happens
| Visitor | Before a choice | Accept / switch on | Decline / switch off |
| --- | --- | --- | --- |
| Must agree, no Do Not Track or Global Privacy Control | Banner. posthog-js does not load: no `/_ph` requests, no PostHog cookies or storage. | posthog-js loads at once, without a reload. | Nothing loads. |
| Must agree, `navigator.doNotTrack === "1"` or `navigator.globalPrivacyControl === true` | No banner. Counts as Decline, also over a stored Accept. | Not possible: the settings switch is off and disabled, and says why. | Nothing loads. A running client opts out. |
| Everyone else | Loads after the page settles, as before. | — | `opt_out_capturing()` and `stopSessionRecording()` run at once. After the next load, posthog-js does not load. |
The gate calls one function, `syncProductAnalytics(config, consent)` in
`ui/src/lib/analytics/product-analytics.ts`. It starts, opts in, opts out or
cancels. Analytics stops whenever the choice is not `granted`, also when it goes back
to "ask" (another tab removes the stored choice, or a session refresh changes
`consentRequired` to `true`). If the choice changes while posthog-js is still
downloading, `init()` does not run until the choice is `granted` again.
The banner sits at the bottom of the page and does not block the board. It
says that recordings hide what the visitor types and their messages,
documents and connected accounts, but can show page names such as task
titles. It links to the privacy policy (https://paperclip.ing/privacy/).
### Where the choice is kept
The choice is per browser, in `localStorage` under
`paperclip.analyticsConsent` (`granted` or `denied`). The latest choice on
the page wins, also when storage rejects the write; it then lasts for the open
page only. Each user can change it in
**Settings → Profile → Product analytics**. The switch shows only when browser
analytics is on for the instance. Turning it on after an earlier opt-out also
clears the PostHog opt-out (`opt_in_capturing()`).
To reset the choice and see the banner again, remove the key in the browser
console: `localStorage.removeItem("paperclip.analyticsConsent")`, then reload.
## Reverse proxy
The browser sends to `/_ph` on its own origin, so ad blockers do not drop
events. `server/src/routes/posthog-proxy.ts` is not a generic proxy. It
forwards only the requests posthog-js makes:
| Method | Path | Upstream |
| --- | --- | --- |
| `POST` | `/e/`, `/i/v0/e/`, `/batch/` | ingest host |
| `POST` | `/s/` (session replay) | ingest host |
| `POST` | `/flags/`, `/decide/` | ingest host |
| `GET` | `/array/<token>/config`, `/array/<token>/config.js` | assets host |
| `GET` | `/static/<name>.js` | assets host |
The ingest host is `PAPERCLIP_POSTHOG_HOST`. The assets host is derived from it
(`us.i.posthog.com` → `us-assets.i.posthog.com`). Every other method or path
answers 404 without contacting PostHog. The proxy streams bodies, builds a new
header set from an allowlist plus `X-Forwarded-For`, and never forwards the
inbound Host, Cookie or Authorization headers. It drops `Set-Cookie` from
responses. It refuses bodies over 64 MiB (413) and limits the requests in
flight (429, see [Proxy limits](#proxy-limits)). It is mounted only when
browser analytics is on. It does not require a session: posthog-js sends some
events while a page unloads, and the proxy can only reach the two PostHog hosts
with the public project token, like PostHog's own ingest endpoint.
### Proxy limits
Each open tab runs posthog-js. One tab sends event batches, session replay
uploads and remote settings requests, so it can have a few requests in flight
at once, and more when PostHog is slow (the proxy waits up to 30 seconds for
an answer). The proxy has two limits. When a request is over a limit, the proxy
answers 429 with `Retry-After: 1`, and posthog-js sends it again later.
| Limit | Default | Variable |
| --- | --- | --- |
| Requests in flight for the whole server | 1024 | `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` |
| Requests in flight from one public client address | 128 | `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT` |
Why these values:
- 128 per address covers about 10 people behind one office network, each with
4 tabs and 3 requests in flight per tab, with space left over.
- 1024 in total keeps memory use bounded. The proxy streams bodies, so a
request holds two sockets and the stream buffers between them, not the full
body. In a local test, 1024 held requests added about 96 MiB of resident
memory with 4 KiB bodies and about 173 MiB with 256 KiB bodies. These
numbers include the test client and the test upstream, which ran in the same
process. Most PostHog bodies are a few KiB.
A value must be a whole number from 1 to 65536 (for example `2048`). The
server reads the values at start. If a value is not valid, the server logs a
warning, uses the default, and starts as usual.
Each request has a deadline of 60 seconds from the time the proxy accepts it,
whether or not data still moves. At the deadline, the proxy stops the request
to PostHog and closes the browser request, so a slow body or a slow answer
cannot hold a slot for longer. This deadline is not configurable. The proxy
also stops a request to PostHog that has no data for 30 seconds.
#### Shared platform hop
The per-client limit uses `req.ip`, which comes from the server's trusted proxy
settings (`TRUST_PROXY`). It never comes from a header the client controls. If
`TRUST_PROXY` is unset behind a platform proxy, `req.ip` is the proxy's private
hop (for example `100.64.x.x` on Railway). All visitors come from that one
address, so a per-client limit would hold back all of them together.
When `req.ip` is not a public address (private, carrier-grade NAT, loopback,
link-local or another reserved range, or no address), the proxy applies only
the total limit. A separate limit for the shared hop would not protect the
visitors behind it: one client that fills it blocks all of them, the same as
with the total limit. The total limit and the request deadline bound the
memory and sockets that clients can use. It does not read `X-Forwarded-For` to find the visitor for a
limit, because a client can write that header. Set `TRUST_PROXY` to the
platform's proxy range so that `req.ip` is the visitor, and the per-client
limit applies again.
#### When the limits are hit
When the proxy refuses a request at a limit, it logs the warning
`PostHog proxy refused requests at its in-flight limit` at most once a minute.
The warning has these fields, and no addresses or other visitor data:
- `refusedAtTotalLimit` and `refusedAtPerClientLimit`: the requests refused
at each limit since the last warning (the first warning counts only one).
- `inFlight`: the requests in flight when the warning was written.
- `maxInFlight` and `maxInFlightPerClient`: the limits in use.
- `sinceMs`: the time since the last warning, or `null` for the first one.
#### Tuning a fleet
Set the variables with a fleet `env_config` campaign, the same way as the
other `PAPERCLIP_POSTHOG_*` variables. Start with a canary stack. The server
reads the values at start, so a campaign that drains and restarts the stacks
applies them at once, and a campaign with `"applyOnNextDeploy": true` applies
them on the next deploy. To go back to the defaults, remove the variables.
Raise `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` when the warning shows refusals
at the total limit and the stack has memory to spare. Raise
`PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT` when it shows refusals at
the per-client limit, for example for a customer with many people behind one
address.
### Visitor location
The `X-Forwarded-For` value that the proxy sends to PostHog carries the
visitor's location. When the socket peer is private, the proxy uses the
rightmost public `X-Forwarded-For` entry, which the platform edge appended.
This value is used only for location, never for limits.
## Identity
- After sign-in: `identify(session.userId, { email, name })`. `session.userId`
is the authenticated actor's user id verbatim (`req.actor.userId`, for
example `paperclip-id:...`), the same id server events use as `distinct_id`. Email and name are person
properties only, never event properties.
- `group("workspace", stackId)`.
- Every event carries `deployment_source: "cloud"` and `environment`. Without
`PAPERCLIP_POSTHOG_ENVIRONMENT`, `environment` is `staging` on a
`*.staging.paperclip.app` host and `production` otherwise.
- Sign-out: `reset()`, called by `useSignOut` before it leaves the page.
- API requests to our own host carry PostHog tracing headers, so server events
link to the browser session.
## Onboarding events
The in-workspace onboarding wizard (`ui/src/components/OnboardingWizard.tsx`)
captures four browser events through `ui/src/lib/analytics/onboarding-analytics.ts`.
They follow the same consent rules as every other browser event: without a
browser analytics config or with consent not granted, nothing is captured.
Events from before posthog-js loads wait in a short queue (at most 50) and keep
their original time. Withdrawing consent or a change of signed-in person drops
the queue.
| Event | When | Properties |
| --- | --- | --- |
| `onboarding_opened` | The wizard opens, once per open. Auto-open (`useAgentlessOnboardingAutoOpen`), a button, and the `/onboarding` route all count. | `step` when the wizard opens on an agent step |
| `onboarding_step_viewed` | A step is shown, once per step change. | `step` |
| `onboarding_step_completed` | The customer moves forward one step, presses Launch on the review step, or Launch finishes. | `step`; `outcome` for `connect_model` (`subscription` or `api_key`) and for `launch` (`succeeded` or `failed`) |
| `onboarding_dismissed` | The wizard closes before Launch finishes, for example when the customer leaves the onboarding page. | `step` when closed on an agent step |
`step` is one of `create_agent`, `connect_model`, `review`, or `launch`. The
organization-naming steps have no `step` value. No event carries free text.
## Privacy
Session replay shows text by default, the way PostHog normally works. Text is
masked only inside marked customer content. Input values and attribute values
are always masked.
- Session replay masks every input value (`maskAllInputs`).
- Replay masks text only inside these markers (`ANALYTICS_MASK_TEXT_SELECTOR`
in `ui/src/lib/analytics/privacy.ts`, passed as rrweb `maskTextSelector`):
- `ANALYTICS_MASK_CLASS` (`ph-mask ph-sensitive`): customer content.
- `ANALYTICS_NO_CAPTURE_CLASS` (`ph-no-capture`): secrets. Replay blocks
these elements entirely.
- `contenteditable` editors (not `contenteditable="false"`).
rrweb masks a text node only when its parent matches the selector or has an
ancestor that matches it. All other text, for example navigation, headings,
buttons, task titles, agent names, project names and company names, is
recorded as it is.
- Replay also masks attribute values (`maskReplayAttribute`): only layout
attributes (`class`, `style`, `role`, `data-state`, SVG geometry and similar),
rrweb metadata and stylesheet links keep their values. `title`,
`aria-label`, `alt`, `placeholder`, `src`, `href`, `data-*` values and
element references (`id`, `for`, `aria-labelledby`) are always masked, so
images record as empty boxes and link targets (for example download links
with file paths) never leave.
- The masking options in `posthog.init` take precedence over the PostHog
project's "Privacy and masking" settings (posthog-js 1.450). posthog-js
ignores the project setting and logs a warning when the two differ. Keep the
project masking settings empty, and change masking only in `privacy.ts`. The
`ph-mask` class is also the posthog-js default `maskTextClass`.
- `ANALYTICS_NO_CAPTURE_CLASS` replaces secrets with a blank box in replays:
every password-type `Input`, environment variable values, new secret
values, and secrets shown as text: one-time sign-in and device codes,
pairing and setup prompts, identity confirmation links, newly issued API
keys and gateway tokens, gateway client snippets, webhook URLs and secrets,
invite claim secrets, raw provider frames and SSH fallback commands.
- Every event and replay meta event goes through `scrubCapturedEvent`
(`before_send`). Every URL keeps only its origin and path: query and hash
values never leave, because they can hold credentials, file paths or search
text. The token segment of `/board-claim/<token>` and `/invite/<token>` is
redacted (`redactAnalyticsUrl`). Other strings only have secret
`key=value` pairs redacted.
- Events never carry the page title (`before_send` drops `title`), because
Paperclip page titles name the task and the organization.
- Autocapture never records element text or attribute values
(`mask_all_text`, `mask_all_element_attributes`). It keeps the click, the
element tree and the page.
- Connected-account content is Google user data or Slack data. No human may
read it in a replay (privacy policy and Google API Limited Use). The
surfaces below, and other free-form text that agents or customers write,
carry `ANALYTICS_MASK_CLASS` on their content element (not on the chrome
around it):
- Rendered markdown (task bodies, comments, chat messages, documents), the
rich editor, task and issue chat threads (messages, tool calls, tool
results, interaction cards), the comment timeline and the file viewer.
- Link preview cards, task quicklook descriptions, external object pills and
rows, and related-work titles.
- Email message cards and email send intents.
- Connection names, connected account names, aliases and email addresses
(Browse rows and the remove dialog, Connections, app detail headers, the
app sidebar, connection choice lists and instructions, aggregator and
Composio account dialogs, Tailscale networks, agent tool and audit
tables, AI connection names, pickers, selects, account details and
controls, pool run details, subscription and quota panels, adapter
sign-in status, connection access and repair cards), GitHub logins
(identity rows, bot people, chat setup, run identity history) and
repositories, Slack workspace names (list and selected value), Slack
account pickers, chat channels, linked user labels, the external task
banner and chat identity pages.
- Connection and account management surfaces are masked by section, not
label by label: the Browse connector list, the App detail body below its
header, the Connections table, Tailscale networks, the chat connection
detail body and its account subtitle, GitHub chat setup, the AI
connection pool editor and the chat identity confirmation. Every dialog,
alert dialog, select (trigger and list), popover, dropdown, sheet and
tooltip under `pages/apps`, `features/connections` and
`components/ai-connections` carries its own mask, because portals escape
the page's masked container; `replay-masking.test.tsx` fails when one
does not.
- App action test results (parsed preview and raw response).
- Inbox and decision rows (subject and detail line), obligation evidence,
Needs You notes and receipts, decision cards and compact decisions,
decision records, and interaction cards (questions, options, answers,
tool action requests, suggested tasks) wherever they render.
- Approval payloads, action card input and reason, recovery card headline,
evidence and options, run ledger retry details and interrupt handoff
previews.
- Run transcripts, run failure details, run events, run stdout and stderr
excerpts (agent page and execution workspace operations), the run
invocation command, notes, prompt, context and environment, Runner
inspector frames, and every preformatted block that shows run output,
tool or webhook payloads, request or response bodies, instructions,
skills or package files.
- Saved connection instructions for agents.
- Document and case revision diffs.
- Search result snippets, toasts (title and body), voice and call
transcripts, case summaries, files and fields, attachment previews and
artifact previews (text, tables, patches and documents).
Component tests render these surfaces with distinctive fixture text and
assert, through `ui/src/lib/analytics/replay-recording.test-utils.ts`, that
the text is rendered but not recorded (or is blocked, for secrets),
including alternate branches, dialog portals and selected values in
closed pickers. `ui/src/lib/analytics/replay-masking.test.tsx` also pins
the remaining surfaces at source level. A new surface that shows
connected-account content needs the class and a test.
- Residual risk: text that the owner accepted as visible can still hold
customer words. Task titles, agent names, project names, company names,
routine names, artifact and document titles, and activity rows (which name
the task or entity) are recorded as they are. Paperclip member names and
email addresses on member, access and profile pages are recorded too. An
agent can copy email or Slack text into a task title. Masking is opt-in per
surface, so a new surface that renders connected-account content without
the class is recorded until somebody marks it.
- The UI never captures an event that the server already sends
(`PAPERCLIP_EVENTS`); `product-analytics-events.test.ts` enforces this.