Merge branch 'master' into fix/cron-monitor-interval-bug

Author: bruno-garcia

.agents/skills/migrate-container-queries/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: migrate-container-queries
+description: Guide for migrating viewport media queries (@media, useMedia) to container queries in Sentry's frontend. Use when migrating responsive layout to container queries, replacing @media/useMedia, refactoring styled responsive components to Container/Flex/Grid primitives, or working on the DE container-query migration.
+---
+
+# Container Query Migration Guide
+
+Migrate viewport-based responsive logic (`@media` + `useMedia`) to container queries so components respond to their own available space instead of the raw viewport.
+
+> **Always do a visual check.** After every migration, resize the _element_ (not just the window) and confirm the layout is identical and flips at the intended width. A good way to narrow an element without touching the window is to open a resizable panel next to it — e.g. drag out the Seer explorer sidebar, which squeezes the middle content. The token scales differ, so a mechanical swap that compiles can still render wrong.
+
+## Approach: refactor first, swap second
+
+Stop at the first rung that fits. Prefer replacing hand-rolled CSS with primitives over a mechanical token swap.
+
+| Rung                   | When                                                                                                    | Do                                                                                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1. Primitive props     | The `@media` only flips layout (`flex-direction`, `display`, `grid-template`, gap, visibility, width)   | Delete the styled component; use `Container`/`Flex`/`Grid`/`Stack` responsive props (`direction={{xs: 'column', md: 'row'}}`)                   |
+| 2. `@container` swap   | CSS can't be a prop (descendant selectors, pseudo-elements, `font-size`, complex `grid-template-areas`) | Keep the styled component; swap `@media` → `@container`, `theme.breakpoints.*` → `theme.container.*`                                            |
+| 3. Container-scoped JS | Width is read in JS to branch rendering                                                                 | Replace `useMedia(...)` with `useResponsivePropValue({...})` for a threshold boolean, or `useContainerBreakpoint()` to branch on the active key |
+| 4. Leave as `useMedia` | Genuine media feature, not width                                                                        | Do nothing — these do not migrate                                                                                                               |
+
+## ⚠️ Convert to the nearest container scale
+
+Breakpoint and container scales have **different keys and different pixel values** — this is not a rename. **MAP BY PIXEL VALUE, NOT BY KEY:** `breakpoints.sm` does NOT become `container.sm`. Reusing the same key is the #1 migration bug.
+
+`theme.breakpoints` (viewport / `@media`), base `2xs`:
+
+| `2xs` | `xs`  | `sm`  | `md`  | `lg`   | `xl`   | `2xl`  |
+| ----- | ----- | ----- | ----- | ------ | ------ | ------ |
+| 0px   | 500px | 800px | 992px | 1200px | 1440px | 2560px |
+
+`theme.container` (container / `@container`), base `zero`:
+
+| `zero` | `3xs` | `2xs` | `xs`  | `sm`  | `md`  | `lg`  | `xl`  | `2xl` | `3xl`  | `4xl`  | `5xl`  |
+| ------ | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ------ | ------ | ------ |
+| 0px    | 320px | 384px | 448px | 512px | 576px | 640px | 768px | 896px | 1024px | 1152px | 1280px |
+
+**Rule:** take the old breakpoint's pixel value and pick the `container` token whose pixel value is _nearest_ to it — not the token with the same name. `breakpoints.sm` is 800px, so it maps to `container.xl` (768px), not `container.sm` (512px). Then confirm with a visual check: the container is often narrower than the viewport, so the nearest-px token is a starting point, not a guarantee.
+
+## Genuine viewport width → `screen:` keys, not `useMedia`
+
+When layout truly must follow the _window_ (not the component's room), don't keep `useMedia` — use a `screen:`-prefixed responsive prop, which resolves against the viewport on the `theme.breakpoints` scale: `direction={{zero: 'column', 'screen:lg': 'row'}}`. Bare keys and `screen:` keys can mix on one prop. Prefer bare (container) keys; reach for `screen:` only when the viewport genuinely drives the layout.
+
+## Keep `useMedia` only for non-width media features
+
+Width — container or viewport — has a prop/hook path above. Leave `useMedia` in place only for:
+`prefers-color-scheme`, `prefers-reduced-motion`, `hover`, `pointer`, `max-height` / height-based, `resolution`, `print`.
+
+## container-type: only when no query container is in scope
+
+**Default: don't add one.** Bare keys and `@container` already resolve against the nearest ancestor container, and product views have one: `ContentStack` (`#main`, `views/organizationLayout/index.tsx`) wraps the routed `<Outlet />` with `containerType="inline-size"`; `topBar` and `#modal-portal` cover their own subtrees. Add `container-type` only when a subtree must respond to _its own_ width rather than the page's — then:
+
+- Use `inline-size` (width only). `size` also queries height, which collapses content unless height is set elsewhere.
+- In a reusable component that may already sit inside a container, make it conditional to avoid a redundant one — `containerType={hasParentQueryContainer ? 'normal' : 'inline-size'}` via `useHasContainerQuery()` (see `components/core/breadcrumbList/breadcrumbList.tsx`).
+
+## Examples
+
+### Rung 1 — styled `@media` → primitive props (preferred)
+
+```tsx
+// Old — delete the styled component
+const Row = styled('div')`
+  display: flex;
+  flex-direction: row;
+  gap: ${p => p.theme.space.md};
+  @media (max-width: ${p => p.theme.breakpoints.sm}) {
+    flex-direction: column;
+  }
+`;
+
+// New
+import {Flex} from '@sentry/scraps/layout';
+<Flex direction={{xs: 'column', sm: 'row'}} gap="md">
+```
+
+### Rung 2 — `@media` → `@container` (when it can't be a prop)
+
+```tsx
+// Old
+@media (max-width: ${p => p.theme.breakpoints.md}) { ... }
+
+// New — swap at-rule AND scale; md breakpoint (992px) → nearest container token by px
+// is 3xl (1024px), NOT theme.container.md by matching key
+@container (max-width: ${p => p.theme.container['3xl']}) { ... }
+```
+
+### Rung 3 — `useMedia` (width) → container-scoped JS
+
+Both helpers below read the nearest query container (call from a descendant of one) and re-render as it crosses a breakpoint. A single `max-width` boolean is cleanest as a responsive value; reach for the active key only when you branch on the key itself.
+
+```tsx
+// Old
+const isNarrow = useMedia(`(max-width: ${theme.breakpoints.sm})`);
+
+// New — resolve a responsive boolean against the container, same mobile-first
+// cascade as CSS. A max-width query is "on by default, off past the threshold",
+// so name only the threshold key. Map by pixel value: breakpoints.sm (800px) →
+// nearest container token is xl (768px).
+import {useResponsivePropValue} from '@sentry/scraps/layout';
+
+const isNarrow = useResponsivePropValue({zero: true, xl: false});
+// below xl → true, at/above xl → false — one key on each side, nothing to enumerate.
+```
+
+Reach for `useContainerBreakpoint()` instead only when you branch on the key
+itself (e.g. picking one of several layouts), not a single threshold. It returns
+the container's active key (`'zero'` … `'5xl'`) — don't compare it with
+`=== 'zero'` for a max-width case: that fires only below 320px and drops the
+320–768px range the original query treated as narrow.
+
+## Migration Checklist
+
+Took the lowest rung that fits (above). Then verify the gotchas:
+
+- [ ] Mapped to the `container` token with the nearest pixel value, not the same name — e.g. `breakpoints.sm` → `container.xl`, not `container.sm`
+- [ ] For width read in JS, used `useResponsivePropValue({...})` for a threshold boolean; reserved `useContainerBreakpoint()` for branching on the key — never `=== 'zero'` to mean "narrow" (that's only <320px)
+- [ ] Routed genuine viewport-width cases to `screen:` keys; kept `useMedia` only for non-width media features
+- [ ] Added `container-type` only when a subtree needs its own; used `inline-size`
+- [ ] Confirmed a query-container ancestor exists (`@container` silently no-ops without one)
+- [ ] **Visual check:** resized the element and confirmed identical output flipping at the intended width

.agents/skills/migrate-container-queries/SPEC.md

@@ -0,0 +1,33 @@
+# Container Query Migration Guide Specification
+
+## Intent
+
+Provide a reliable, low-risk path for converting viewport-based responsive logic (`@media`, `useMedia`) to container queries, so components respond to their own available width instead of the raw viewport. The dominant failure mode this skill guards against is mapping a breakpoint token to the container token of the same name: the two scales share names but not pixel values.
+
+## Scope
+
+In scope: migrating `@media`/`useMedia` width logic to primitive props, `@container` CSS, `useContainerBreakpoint()`, or `screen:` keys, and deciding when to add `container-type`.
+
+Out of scope: non-width media features (`prefers-*`, `hover`, `pointer`, `resolution`, height-based, `print`) stay on `useMedia`; building the primitives or tokens themselves.
+
+## Non-negotiable Constraints
+
+- Map to the `container` token with the pixel value _nearest_ the old breakpoint's — never the same-named token.
+- Always visually verify by resizing the element (the container is often narrower than the viewport, so the nearest-px token is a starting point).
+- Route genuine viewport-width cases to `screen:` keys; keep `useMedia` only for non-width media features.
+
+## Sources
+
+- Scraps `Container` story, "Container Queries" section — authoritative for container vs. `screen:` keys, both token scales, `useContainerBreakpoint`, and `container-type` guidance.
+- Reference migration PR getsentry/sentry#120315 (trace-view).
+- `components/core/breadcrumbList/breadcrumbList.tsx` — conditional `container-type` pattern.
+
+## Known Limitations
+
+- The nearest-px token is only a starting point; the true reflow width needs a browser visual check the skill cannot perform.
+- `@container` silently no-ops without a query-container ancestor; the skill flags this but cannot detect it statically.
+
+## Maintenance
+
+- Update `SKILL.md` when token scales change, primitives gain/lose props, or a rung is added.
+- Update `SPEC.md` when intent, scope, the non-negotiable constraints, or the sources change.

.agents/skills/seer-embed/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: seer-embed
+description: Add a new Seer embed widget — a rich component rendered inline in Seer's markdown output via tag syntax. Covers schema, component, registration, and backend codegen. Use when asked to "add an embed", "new seer embed", "create a seer widget", "add a markdown widget", "new seer tag", or "embed widget".
+---
+
+# Add a Seer Embed
+
+Seer embeds are rich widgets rendered inline in Seer's markdown output using Markdoc-style tag syntax (`{% name %}{ ... }{% /name %}`). Each embed has a Zod schema, a React component, and a registry entry.
+
+## Before You Start
+
+1. Read `static/app/components/seer/markdown/embeds/schemas.ts` to see existing schemas.
+2. Read `static/app/components/seer/markdown/embeds/index.ts` to see registered embeds.
+3. Confirm the embed name doesn't already exist.
+
+## Step 1: Add the Schema
+
+In `static/app/components/seer/markdown/embeds/schemas.ts`, add an entry to `SEER_EMBED_SCHEMAS`:
+
+```ts
+export const SEER_EMBED_SCHEMAS = {
+  // ...existing entries
+
+  myEmbed: {
+    description:
+      "One sentence describing what this embed does—this passes through directly to the LLM's system prompt.",
+    level: ['inline'], // 'inline', 'block', or both
+    schema: z.object({
+      // Define the data shape the LLM will produce
+      someField: z.string(),
+      optionalField: z.number().optional(),
+    }),
+    examples: [{label: 'Basic', data: {someField: 'hello'}}],
+    // featureFlag: 'organizations:seer-explorer-my-embed',  // optional
+  },
+} as const satisfies Record<string, SeerEmbedSchema>;
+```
+
+**Key decisions:**
+
+- **`description`**: Write for the LLM — it uses this to decide when to emit the embed. Be specific about the use case.
+- **`level`**: Use `['inline']` for widgets that flow within text (timestamps, badges). Use `['block']` for widgets that need their own line (cards, charts). Use both if the embed adapts.
+- **`schema`**: Use Zod. Keep it flat and simple — the LLM has to produce valid JSON. Use `.default()` for optional fields with sensible defaults. Use `.enum()` to constrain string values.
+- **`examples`**: An array of `{label, data, level?}` objects. Each `data` must be valid against the schema. These are included in the generated JSON sent to the LLM as few-shot examples. In the stories page, all examples for an embed are composed into a single markdown block and rendered through one `<SeerMarkdown>` — inline examples are wrapped in prose text, block examples are appended at the end. Use multiple examples to show different prop combinations or block vs inline rendering. Set `level` on an example only when it differs from the schema's default (first entry in `level`).
+- **`featureFlag`**: Set this to gate the embed behind a feature flag. The backend filters it out of the schema sent to the LLM when the flag is off.
+
+## Step 2: Create the Component
+
+Create `static/app/components/seer/markdown/embeds/components/<name>.tsx`:
+
+```tsx
+import {defineSeerEmbed} from 'sentry/components/seer/markdown/embeds/utils';
+
+export const MyEmbed = defineSeerEmbed({
+  name: 'myEmbed', // must match the key in SEER_EMBED_SCHEMAS
+  render({someField, optionalField}) {
+    // Props are typed from the Zod schema — already validated
+    return <span>{someField}</span>;
+  },
+});
+```
+
+**What `defineSeerEmbed` does for you:**
+
+- Looks up the Zod schema by name
+- `safeParse`s the `data` prop against it
+- Returns `null` for invalid data (logs a warning in dev)
+- Sets `displayName` on the component (used by the registry)
+
+**Rules:**
+
+- The `name` parameter **must** match the key in `SEER_EMBED_SCHEMAS` exactly.
+- The `render` function receives the Zod output type — props are already parsed and validated.
+- Keep the component simple. Import existing Sentry components (`DateTime`, `TimeSince`, `Link`, etc.) rather than building from scratch.
+- The component receives no context about where it appears — it only gets the data from the tag body.
+
+## Step 3: Register the Component
+
+In `static/app/components/seer/markdown/embeds/index.ts`, import and add it to the `embeds` array:
+
+```ts
+import {MyEmbed} from './components/myEmbed';
+import {Timestamp} from './components/timestamp';
+import {SeerEmbedRegistry} from './registry';
+
+const embeds = [Timestamp, MyEmbed];
+for (const embed of embeds) {
+  SeerEmbedRegistry.register(embed.displayName, embed);
+}
+```
+
+Registration uses `displayName` (set by `defineSeerEmbed`) as the registry key.
+
+## Step 4: Regenerate Backend Schema
+
+Run the codegen script to update the JSON Schema file the backend sends to the Seer agent:
+
+```bash
+pnpm gen:embed-widgets
+```
+
+This writes to `src/sentry/seer/agent/embed_widgets.generated.json`. **Commit this generated file** — it's checked in, not gitignored.
+
+## Step 5: Verify
+
+1. **Lint**: Run `pnpm run lint:js` on your new files.
+2. **Types**: Run `pnpm run typecheck` to confirm the schema types flow through.
+3. **Manual test**: In the Seer Explorer, trigger a response that would use your embed. Or test directly:
+
+```tsx
+<SeerMarkdown raw={`{% myEmbed %}{"someField":"hello"}{% /myEmbed %}`} />
+```
+
+## File Summary
+
+| File                                                               | What to do                              |
+| ------------------------------------------------------------------ | --------------------------------------- |
+| `static/app/components/seer/markdown/embeds/schemas.ts`            | Add Zod schema entry                    |
+| `static/app/components/seer/markdown/embeds/components/<name>.tsx` | Create component with `defineSeerEmbed` |
+| `static/app/components/seer/markdown/embeds/index.ts`              | Import and register                     |
+| `src/sentry/seer/agent/embed_widgets.generated.json`               | Regenerated by `pnpm gen:embed-widgets` |
+
+## Optional: Feature Flag
+
+If the embed should be gated:
+
+1. Add `featureFlag: 'organizations:seer-explorer-<name>'` to the schema entry.
+2. Register the flag in `src/sentry/features/temporary.py`.
+3. The backend (`src/sentry/seer/agent/embed_widgets.py`) automatically filters flagged embeds using `features.has()`.

.github/CODEOWNERS

@@ -577,6 +577,7 @@ tests/sentry/api/endpoints/test_organization_attribute_mappings.py          @get
 
 ## SDK
 /src/sentry/utils/sdk.py                                             @getsentry/team-web-sdk-backend
+/src/sentry/utils/tracing.py                                         @getsentry/team-web-sdk-backend
 /src/sentry/build/                                                   @getsentry/team-web-sdk-backend
 /src/sentry/api/endpoints/source_map_debug.py                        @getsentry/team-javascript-sdks
 /src/sentry/web/frontend/setup_wizard.py                             @getsentry/team-javascript-sdks
@@ -601,6 +602,8 @@ tests/sentry/api/endpoints/test_organization_attribute_mappings.py          @get
 /src/sentry/relay/config/ai_model_costs.py                                       @getsentry/telemetry-experience
 /src/sentry/tasks/ai_agent_monitoring.py                                         @getsentry/telemetry-experience
 /tests/sentry/tasks/test_ai_agent_monitoring.py                                  @getsentry/telemetry-experience
+/src/sentry/ai_monitoring/                                                       @getsentry/telemetry-experience
+/tests/sentry/ai_monitoring/                                                     @getsentry/telemetry-experience
 /static/app/actionCreators/metrics.tsx                                           @getsentry/telemetry-experience
 /static/app/views/settings/dynamicSampling/                                      @getsentry/telemetry-experience
 /static/app/views/insights/pages/agents/                                         @getsentry/telemetry-experience

.github/actions/setup-node-pnpm/action.yml

@@ -14,7 +14,7 @@ runs:
       id: nodemodulescache
       with:
         path: node_modules
-        key: ${{ runner.os }}-node-modules-${{ hashFiles('pnpm-lock.yaml', 'api-docs/pnpm-lock.yaml', '.node-version') }}
+        key: ${{ runner.os }}-node-modules-${{ hashFiles('pnpm-lock.yaml', '.node-version') }}
 
     - name: Install Javascript Dependencies
       if: steps.nodemodulescache.outputs.cache-hit != 'true'