Merge branch 'develop' into fix-react-componentStack

Author: harshit078

.agents/skills/add-ai-integration/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: add-ai-integration
+description: Add a new AI provider integration to the Sentry JavaScript SDK. Use when contributing a new AI instrumentation (OpenAI, Anthropic, Vercel AI, LangChain, etc.) or modifying an existing one.
+argument-hint: <provider-name>
+---
+
+# Adding a New AI Integration
+
+## Decision Tree
+
+```
+Does the AI SDK have native OpenTelemetry support?
+|- YES -> Does it emit OTel spans automatically?
+|   |- YES (like Vercel AI) -> Pattern 1: OTel Span Processors
+|   +- NO -> Pattern 2: OTel Instrumentation (wrap client)
++- NO -> Does the SDK provide hooks/callbacks?
+    |- YES (like LangChain) -> Pattern 3: Callback/Hook Based
+    +- NO -> Pattern 4: Client Wrapping
+```
+
+## Runtime-Specific Placement
+
+If an AI SDK only works in one runtime, code lives exclusively in that runtime's package. Do NOT add it to `packages/core/`.
+
+- **Node.js-only** -> `packages/node/src/integrations/tracing/{provider}/`
+- **Cloudflare-only** -> `packages/cloudflare/src/integrations/tracing/{provider}.ts`
+- **Browser-only** -> `packages/browser/src/integrations/tracing/{provider}/`
+- **Multi-runtime** -> shared core in `packages/core/src/tracing/{provider}/` with runtime-specific wrappers
+
+## Span Hierarchy
+
+- `gen_ai.invoke_agent` — parent/pipeline spans (chains, agents, orchestration)
+- `gen_ai.chat`, `gen_ai.generate_text`, etc. — child spans (actual LLM calls)
+
+## Shared Utilities (`packages/core/src/tracing/ai/`)
+
+- `gen-ai-attributes.ts` — OTel Semantic Convention attribute constants. **Always use these, never hardcode.**
+- `utils.ts` — `setTokenUsageAttributes()`, `getTruncatedJsonString()`, `truncateGenAiMessages()`, `buildMethodPath()`
+- Only use attributes from [Sentry Gen AI Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/).
+
+## Streaming
+
+- **Non-streaming:** `startSpan()`, set attributes from response
+- **Streaming:** `startSpanManual()`, accumulate state via async generator or event listeners, set `GEN_AI_RESPONSE_STREAMING_ATTRIBUTE: true`, call `span.end()` in finally block
+- Detect via `params.stream === true`
+- References: `openai/streaming.ts` (async generator), `anthropic-ai/streaming.ts` (event listeners)
+
+## Token Accumulation
+
+- **Child spans:** Set tokens directly from API response via `setTokenUsageAttributes()`
+- **Parent spans (`invoke_agent`):** Accumulate from children using event processor (see `vercel-ai/`)
+
+## Pattern 1: OTel Span Processors
+
+**Use when:** SDK emits OTel spans automatically (Vercel AI)
+
+1. **Core:** Create `add{Provider}Processors()` in `packages/core/src/tracing/{provider}/index.ts` — registers `spanStart` listener + event processor
+2. **Node.js:** Add `callWhenPatched()` optimization in `packages/node/src/integrations/tracing/{provider}/index.ts` — defers registration until package is imported
+3. **Edge:** Direct registration in `packages/cloudflare/src/integrations/tracing/{provider}.ts` — no OTel, call processors immediately
+
+Reference: `packages/node/src/integrations/tracing/vercelai/`
+
+## Pattern 2: OTel Instrumentation (Client Wrapping)
+
+**Use when:** SDK has no native OTel support (OpenAI, Anthropic, Google GenAI)
+
+1. **Core:** Create `instrument{Provider}Client()` in `packages/core/src/tracing/{provider}/index.ts` — Proxy to wrap client methods, create spans manually
+2. **Node.js `instrumentation.ts`:** Patch module exports, wrap client constructor. Check `_INTERNAL_shouldSkipAiProviderWrapping()` for LangChain compatibility.
+3. **Node.js `index.ts`:** Export integration function using `generateInstrumentOnce()` helper
+
+Reference: `packages/node/src/integrations/tracing/openai/`
+
+## Pattern 3: Callback/Hook Based
+
+**Use when:** SDK provides lifecycle hooks (LangChain, LangGraph)
+
+1. **Core:** Create `create{Provider}CallbackHandler()` — implement SDK's callback interface, create spans in callbacks
+2. **Node.js `instrumentation.ts`:** Auto-inject callbacks by patching runnable methods. Disable underlying AI provider wrapping.
+
+Reference: `packages/node/src/integrations/tracing/langchain/`
+
+## Auto-Instrumentation (Node.js)
+
+**Mandatory** for Node.js AI integrations. OTel only patches when the package is imported (zero cost if unused).
+
+### Steps
+
+1. **Add to `getAutoPerformanceIntegrations()`** in `packages/node/src/integrations/tracing/index.ts` — LangChain MUST come first
+2. **Add to `getOpenTelemetryInstrumentationToPreload()`** for OTel-based integrations
+3. **Export from `packages/node/src/index.ts`**: integration function + options type
+4. **Add E2E tests:**
+   - Node.js: `dev-packages/node-integration-tests/suites/tracing/{provider}/`
+   - Cloudflare: `dev-packages/cloudflare-integration-tests/suites/tracing/{provider}/`
+   - Browser: `dev-packages/browser-integration-tests/suites/tracing/ai-providers/{provider}/`
+
+## Key Rules
+
+1. Respect `sendDefaultPii` for `recordInputs`/`recordOutputs`
+2. Set `SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN = 'auto.ai.{provider}'` (alphanumerics, `_`, `.` only)
+3. Truncate large data with helper functions from `utils.ts`
+4. `gen_ai.invoke_agent` for parent ops, `gen_ai.chat` for child ops
+
+## Checklist
+
+- [ ] Runtime-specific code placed only in that runtime's package
+- [ ] Added to `getAutoPerformanceIntegrations()` in correct order (Node.js)
+- [ ] Added to `getOpenTelemetryInstrumentationToPreload()` (Node.js with OTel)
+- [ ] Exported from appropriate package index
+- [ ] E2E tests added and verifying auto-instrumentation
+- [ ] Only used attributes from [Sentry Gen AI Conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/)
+- [ ] JSDoc says "enabled by default" or "not enabled by default"
+- [ ] Documented how to disable (if auto-enabled)
+- [ ] Verified OTel only patches when package imported (Node.js)
+
+## Reference Implementations
+
+- **Pattern 1 (Span Processors):** `packages/node/src/integrations/tracing/vercelai/`
+- **Pattern 2 (Client Wrapping):** `packages/node/src/integrations/tracing/openai/`
+- **Pattern 3 (Callback/Hooks):** `packages/node/src/integrations/tracing/langchain/`
+
+**When in doubt, follow the pattern of the most similar existing integration.**

.agents/skills/add-cdn-bundle/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: add-cdn-bundle
+description: Create a new CDN bundle for the browser package with specified features
+argument-hint: <feature-combo> (e.g., replay.logs.metrics, tracing.logs, tracing.replay.feedback.logs.metrics)
+---
+
+# Add CDN Bundle Skill
+
+This skill creates a new CDN bundle for the browser package that includes a specific combination of features.
+
+## Input
+
+The user provides a feature combination using dot notation:
+
+- `logs.metrics` - Bundle with logs and metrics
+- `replay.logs.metrics` - Bundle with replay, logs, and metrics
+- `tracing.replay.logs` - Bundle with tracing, replay, and logs
+- `tracing.replay.feedback.logs.metrics` - Full featured bundle
+
+**Feature order in bundle names:** `tracing` → `replay` → `feedback` → `logs` → `metrics`
+
+## Instructions
+
+Follow the detailed guide at [docs/adding-cdn-bundle.md](../../../docs/adding-cdn-bundle.md) to create the bundle.
+
+### Quick Reference - Naming Conventions
+
+Given a feature combination, derive these variants:
+
+| Placeholder                     | Example (`replay.logs.metrics`) |
+| ------------------------------- | ------------------------------- |
+| `{FEATURE_COMBO}`               | `replay.logs.metrics`           |
+| `{feature_combo}`               | `replay_logs_metrics`           |
+| `{featureCombo}`                | `replayLogsMetrics`             |
+| `{Human Readable Features}`     | `Replay, Logs, Metrics`         |
+| `{Human Readable Feature List}` | `Replay, Logs, and Metrics`     |
+
+### Quick Reference - Files to Create/Modify
+
+1. **Create** `packages/browser/src/index.bundle.{FEATURE_COMBO}.ts`
+2. **Create** `packages/browser/test/index.bundle.{FEATURE_COMBO}.test.ts`
+3. **Modify** `packages/browser/rollup.bundle.config.mjs`
+4. **Modify** `.size-limit.js`
+5. **Modify** `dev-packages/browser-integration-tests/package.json`
+6. **Modify** `dev-packages/browser-integration-tests/utils/generatePlugin.ts`
+7. **Modify** `.github/workflows/build.yml`
+
+### Verification Steps
+
+After making changes:
+
+```bash
+yarn lint
+cd packages/browser && yarn build:dev
+cd packages/browser && yarn test
+```

.agents/skills/bump-size-limit/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: bump-size-limit
+description: Bump size limits in .size-limit.js when the size-limit CI check is failing. Use when the user mentions size limit failures, bundle size checks failing, CI size check errors, or needs to update size-limit thresholds. Also use when the user says "bumpSizeLimit", "fix size limit", "size check failing", or "update bundle size limits".
+---
+
+# Bump Size Limit
+
+When the size-limit GitHub Action fails, it means one or more bundle scenarios exceed their configured byte thresholds in `.size-limit.js`. This skill walks through building, measuring, and bumping only the limits that need it.
+
+## Workflow
+
+### Step 1: Build all packages (including CDN bundles)
+
+A full build is required because size-limit measures the actual compiled artifacts.
+
+```bash
+yarn build
+```
+
+This takes a few minutes. CDN bundles in `packages/browser/build/bundles/` must be up to date — a dev build is not sufficient.
+
+### Step 2: Run the size check in JSON mode
+
+```bash
+yarn test:size-limit
+```
+
+The JSON output is an array of objects. Each object has:
+
+- `name` — the scenario label
+- `passed` — whether it's within the limit
+- `size` — actual size in bytes
+- `sizeLimit` — configured limit in bytes
+
+### Step 3: Identify failed scenarios
+
+Filter for entries where `"passed": false`. These are the only ones that need bumping.
+
+### Step 4: Calculate new limits
+
+For each failed scenario, round the actual size **up to the next full KB** (1 KB = 1000 bytes in this context, matching how size-limit interprets the limits in `.size-limit.js`).
+
+**Example:** If actual size is `129,127` bytes, the new limit is `130 KB` (i.e. 130,000 bytes).
+
+The heuristic is intentionally conservative — it gives just enough headroom without inflating limits unnecessarily.
+
+### Step 5: Update `.size-limit.js`
+
+Open `.size-limit.js` at the repository root and update the `limit` field for each failed scenario. Limits are strings like `'130 KB'`.
+
+Only change limits for scenarios that actually failed. Do not touch passing scenarios.
+
+### Step 6: Verify the fix
+
+Re-run size-limit to confirm everything passes:
+
+```bash
+yarn test:size-limit
+```
+
+If any scenario still fails (e.g., due to rounding edge cases), bump that specific limit by another 1 KB and re-run.

.agents/skills/dotagents/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: dotagents
+description: Manage agent skill dependencies with dotagents. Use when asked to "add a skill", "install skills", "remove a skill", "update skills", "dotagents init", "agents.toml", "agents.lock", "sync skills", "list skills", "set up dotagents", "configure trust", "add MCP server", "add hook", "wildcard skills", "user scope", or any dotagents-related task.
+---
+
+Manage agent skill dependencies declared in `agents.toml`. dotagents resolves, installs, and symlinks skills so multiple agent tools (Claude Code, Cursor, Codex, VS Code, OpenCode) discover them from `.agents/skills/`.
+
+## Running dotagents
+
+If `dotagents` is not available as a direct command, use `npx @sentry/dotagents` instead. For example: `npx @sentry/dotagents sync`. All commands and flags work the same way.
+
+## References
+
+Read the relevant reference when the task requires deeper detail:
+
+| Document                                                   | Read When                                                                 |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------- |
+| [references/cli-reference.md](references/cli-reference.md) | Full command options, flags, examples                                     |
+| [references/configuration.md](references/configuration.md) | Editing agents.toml, source formats, trust, MCP, hooks, wildcards, scopes |
+| [references/config-schema.md](references/config-schema.md) | Exact field names, types, and defaults                                    |
+
+## Quick Start
+
+```bash
+# Initialize a new project (interactive TUI)
+dotagents init
+
+# Add a skill from GitHub
+dotagents add getsentry/skills find-bugs
+
+# Add multiple skills at once
+dotagents add getsentry/skills find-bugs code-review commit
+
+# Add all skills from a repo
+dotagents add getsentry/skills --all
+
+# Add a pinned skill
+dotagents add getsentry/warden@v1.0.0
+
+# Install all dependencies from agents.toml
+dotagents install
+
+# List installed skills
+dotagents list
+```
+
+## Commands
+
+| Command                     | Description                                                        |
+| --------------------------- | ------------------------------------------------------------------ |
+| `dotagents init`            | Initialize `agents.toml` and `.agents/` directory                  |
+| `dotagents install`         | Install all skills from `agents.toml`                              |
+| `dotagents add <specifier>` | Add a skill dependency                                             |
+| `dotagents remove <name>`   | Remove a skill                                                     |
+| `dotagents update [name]`   | Update skills to latest versions                                   |
+| `dotagents sync`            | Reconcile state (adopt orphans, repair symlinks, verify integrity) |
+| `dotagents list`            | Show installed skills and their status                             |
+| `dotagents mcp`             | Add, remove, or list MCP server declarations                       |
+
+All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project.
+
+For full options and flags, read [references/cli-reference.md](references/cli-reference.md).
+
+## Source Formats
+
+| Format           | Example                                | Description                           |
+| ---------------- | -------------------------------------- | ------------------------------------- |
+| GitHub shorthand | `getsentry/skills`                     | Owner/repo (resolves to GitHub HTTPS) |
+| GitHub pinned    | `getsentry/warden@v1.0.0`              | With tag, branch, or commit           |
+| GitHub SSH       | `git@github.com:owner/repo.git`        | SSH clone URL                         |
+| GitHub HTTPS     | `https://github.com/owner/repo`        | Full HTTPS URL                        |
+| Git URL          | `git:https://git.corp.dev/team/skills` | Any non-GitHub git remote             |
+| Local path       | `path:./my-skills/custom`              | Relative to project root              |
+
+## Key Concepts
+
+- **`.agents/skills/`** is the canonical home for all installed skills
+- **`agents.toml`** declares dependencies; **`agents.lock`** pins exact commits and integrity hashes
+- **Symlinks**: `.claude/skills/`, `.cursor/skills/` point to `.agents/skills/`
+- **Wildcards**: `name = "*"` installs all skills from a source, with optional `exclude` list
+- **Trust**: Optional `[trust]` section restricts which sources are allowed
+- **Hooks**: `[[hooks]]` declarations write tool-event hooks to each agent's config
+- **Gitignore**: When `gitignore = true`, managed skills are gitignored; custom in-place skills are tracked
+- **User scope**: `--user` flag manages skills in `~/.agents/` shared across all projects