You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docs half of the browser-telemetry control / platform split (kernel-images#322, kernel-images#323, kernel#3086). Two things on this page stop being true when that ships, one of them in a way that matters for compliance.
control narrows. It was "computer-control API calls against the session" and in practice every in-VM API endpoint. It is now the actions that drive the browser — computer controls, Playwright execution, screenshots, clipboard — plus cdp_command for browser-control commands sent over the CDP proxy.
platform is new, opt-in, and carries the VM-management traffic that used to sit in control (recording lifecycle, filesystem, process, telemetry and browser configuration). Documented with when you'd actually want it: debugging a profile save or a replay rather than the agent.
The sensitivity table was wrong once code landed. It grouped control with the categories that carry "session metadata only ... no page content", and api_call now carries the source submitted for Playwright execution — in a category that is on by default. The row now says so, notes the 8 KB clip, and states what cdp_command deliberately does not capture (typed text, key names, navigation URLs — only the character count).
Actionable guidance rather than just a warning: pass credentials into Playwright snippets through variables instead of as literals, so the captured source doesn't carry them. Same note added to the BAA warning, since control stays available to BAA orgs when network / console / screenshot don't.
The default-set description on the overview page is unchanged and still correct — the default set is still control, connection, system, captcha.
Sequencing
Should merge with or just after the kernel-images release and kernel#3086, not before: until then platform isn't selectable and control still carries the platform traffic.
Notes
Left formatting alone — this file doesn't currently satisfy prettier at baseline and CI only checks broken links, so running it would bury the change in reflowed tables. No new links added.
Review round
Three accuracy fixes after checking every claim against the generated operation-to-category map and the emitting code:
The platform row omitted three operations it covers: log streaming and both scale-to-zero calls. Added.
"clipped to 8192 characters" was wrong — the cap is 8 KB of bytes, trimmed to a character boundary. Now reads 8 KB, and both API specs were corrected to say bytes.
"one action reads as one event" overstated the phase collapsing: a click is still a press and a release. Reworded, and the named-key explanation now matches the allowlist the code actually uses rather than a character-count rule.
Documentation-only MDX update: revises the control category description, documents a new platform category, and corrects the data-sensitivity table / guidance around Playwright code capture and CDP command redaction
No application logic, APIs, auth, infra, config, or schema changes
No CODEOWNERS file present
Risk factors
Factor
Assessment
Codepaths modified
Docs content only
Blast radius
Readers of telemetry category docs
Complexity
Low — prose/table updates
Infrastructure impact
None
Operational / security risk
None in code; content clarifies sensitivity semantics
Decision
Still meets Very Low criteria (documentation-only, small scoped diff, no production logic or shared-system changes). Risk is unchanged from the prior approval, so approval is not revoked and the PR is not re-approved.
`control` used to be every in-VM API call, and the sensitivity table described
the whole default set as session metadata with no page content. Both are about
to stop being true: `control` narrows to actions that drive the browser and
gains the submitted Playwright source on `api_call`, VM-management calls move to
a new opt-in `platform` category, and browser-control commands sent over the CDP
proxy arrive as `cdp_command`.
The sensitivity table now calls out that a default-on category carries submitted
source, with the practical advice that follows from it: pass credentials through
variables rather than as literals in the snippet. Callers under a BAA get the
same note, since `control` stays available to them when the browser-activity
categories don't.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Documentation-only MDX update: revises the control category description, documents a new platform category, and corrects the data-sensitivity table / guidance around Playwright code capture and CDP command redaction
No application logic, APIs, auth, infra, config, or schema changes
No CODEOWNERS file present
Risk factors
Factor
Assessment
Codepaths modified
Docs content only
Blast radius
Readers of telemetry category docs
Complexity
Low — prose/table updates
Infrastructure impact
None
Operational / security risk
None in code; content clarifies sensitivity semantics
Decision
Still meets Very Low criteria (documentation-only, small scoped diff, no production logic or shared-system changes). Risk is unchanged from the prior approval, so approval is not revoked and the PR is not re-approved.
#322)
## Summary
- every operation in `openapi.yaml` declares `x-telemetry-category`;
`categorygen` emits the operation → category map next to the event-type
map, so a new endpoint without a classification fails generation instead
of landing somewhere silently
- browser-control operations (computer actions, `executePlaywrightCode`,
screenshot, clipboard) keep emitting `api_call` under `control`;
VM-management operations emit a new `platform_api_call` under a new
`platform` category
- `platform` is opt-in: in `UserCategories`, not `DefaultCategories`, so
enabling telemetry without per-category settings now captures strictly
less than before
- `BrowserApiCallEventData` gains `code`, recorded for
`executePlaywrightCode` and capped by the same helper and constant as
every other captured string
- `operation_id` description corrected — the value on the wire is the
generated handler name (`ProcessExec`), and `categorygen` rejects any
operationId that isn't lowerCamelCase, since that assumption is what
makes the mapping safe
## Why
`api_call` fired for every documented operation and always landed in
`control`. Most of that traffic is the platform acting on the VM, not an
agent acting on the browser: `listRecorders` polling, profile save and
restore (`downloadDirZstd`, `deleteDirectory`, `processExec`), replay
lifecycle, telemetry publishing itself. Reading `control` to see what an
agent did meant paging past all of it, and the one event worth reading —
`executePlaywrightCode` — didn't include the code that ran.
## Classification calls worth a second look
`takeScreenshot` and `readClipboard`/`writeClipboard` are `control`: an
agent uses them to see and to move data. `patchDisplay`,
`chromiumConfigure`, `patchChromiumFlags` and
`uploadExtensionsAndRestart` are `platform` — browser configuration
issued at session setup. `processExec` is `platform` even though a
customer can call it directly, because it isn't browser control. An
operation the generated map doesn't know falls back to `platform`, so an
unclassified route can't dilute the stream callers read to see agent
behavior.
## Sequencing
`control` narrows here with no opt-in path back until the control-plane
half lands (kernel#3086), so anyone reading `control` for profile-save
or replay calls needs `platform` after this release. CDP-level control
events are #323, stacked on this branch and shipping in the same
release. Docs are kernel/docs#474.
## Captured-string cap
`code` reuses what already existed rather than adding a second
convention. `truncateBody` and the 8 KB structured-body cap moved out of
`lib/cdpmonitor` into `lib/events` as `TruncateCaptured` and
`CapturedFieldCap`, so response bodies and submitted source now share
one helper, one constant and one marker (`...[truncated]`), and the
constant carries the reason for its value: three orders of magnitude
below `maxS2RecordBytes`, so no single field can push an envelope past
the record limit and null the whole payload. A clipped value is marked
in the string, so `truncated` on the envelope keeps meaning only what
`truncateIfNeeded` sets it to. The helper had no tests before; it has
them now.
## Generated handler names
`categorygen` no longer derives the handler name from the operationId by
uppercasing the first letter, which assumed how oapi-codegen spells a
name and needed a lowerCamelCase guard to be safe. It now reads the
generated `ServerInterface`, whose methods each document the route they
serve, and joins that to the spec on method and path. Nothing about
naming is assumed, and generation fails if a classified route has no
handler, if a handler has no classification, or if the two counts
disagree. The regenerated map is byte-identical to the derived one.
## Testing
- `make test-unit` — `go vet ./...` clean, unit suite green
- `test-server-unit` green on this commit in CI
- new: unit coverage for `TruncateCaptured` (cap, rune boundary, marker,
sub-marker caps), for the operation → category map, and for the `code`
cap end to end through the middleware
- `categorygen` failure modes exercised by hand: a spec route with no
generated handler, an operation with no `x-telemetry-category`, and a
missing handlers file each exit non-zero with the route named
- e2e not run — needs Docker
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Changes telemetry event shapes, default capture scope, and how API
routes are classified—callers relying on all HTTP calls in `control`
must opt into `platform`; misclassified routes would skew observability
but unclassified routes safely fall back to platform.
>
> **Overview**
> **Splits VM-management HTTP traffic out of the `control` telemetry
stream** so `control` reflects browser-driving calls (computer actions,
Playwright, screenshots, clipboard) while a new **`platform`** category
carries **`platform_api_call`** for recording, FS, process, telemetry
config, Chromium setup, and similar.
>
> Each OpenAPI operation now declares **`x-telemetry-category`**.
**`categorygen`** builds both event-type and operation→category maps by
joining the spec to the generated **`ServerInterface`** route comments
(not derived operationId spelling). CI runs **`go generate`** and fails
if **`category_gen.go`** is stale. Unmapped operations **default to
platform** so they cannot pollute `control`.
>
> **`ExecutePlaywrightCode`** calls **`RecordTelemetryCode`**; submitted
source appears on **`api_call`** as optional **`code`**, capped via
shared **`events.TruncateCaptured`** / **`CapturedFieldCap`** (CDP body
capture uses the same helper). Telemetry middleware stays enabled when
**either** `control` or **`platform`** is captured.
>
> Default telemetry categories **exclude `platform`** (opt-in). OpenAPI
and generated types add **`BrowserPlatformApiCallEvent`** and config
knobs for **`platform`**.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
0a64ebd. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Summary
Docs half of the browser-telemetry
control/platformsplit (kernel-images#322, kernel-images#323, kernel#3086). Two things on this page stop being true when that ships, one of them in a way that matters for compliance.controlnarrows. It was "computer-control API calls against the session" and in practice every in-VM API endpoint. It is now the actions that drive the browser — computer controls, Playwright execution, screenshots, clipboard — pluscdp_commandfor browser-control commands sent over the CDP proxy.platformis new, opt-in, and carries the VM-management traffic that used to sit incontrol(recording lifecycle, filesystem, process, telemetry and browser configuration). Documented with when you'd actually want it: debugging a profile save or a replay rather than the agent.codelanded. It groupedcontrolwith the categories that carry "session metadata only ... no page content", andapi_callnow carries the source submitted for Playwright execution — in a category that is on by default. The row now says so, notes the 8 KB clip, and states whatcdp_commanddeliberately does not capture (typed text, key names, navigation URLs — only the character count).controlstays available to BAA orgs whennetwork/console/screenshotdon't.The default-set description on the overview page is unchanged and still correct — the default set is still
control,connection,system,captcha.Sequencing
Should merge with or just after the kernel-images release and kernel#3086, not before: until then
platformisn't selectable andcontrolstill carries the platform traffic.Notes
Left formatting alone — this file doesn't currently satisfy prettier at baseline and CI only checks broken links, so running it would bury the change in reflowed tables. No new links added.
Review round
Three accuracy fixes after checking every claim against the generated operation-to-category map and the emitting code:
platformrow omitted three operations it covers: log streaming and both scale-to-zero calls. Added.