diff --git a/.changeset/flush-diff-lines.md b/.changeset/flush-diff-lines.md new file mode 100644 index 00000000000..c4411d48629 --- /dev/null +++ b/.changeset/flush-diff-lines.md @@ -0,0 +1,5 @@ +--- +'@mastra/playground-ui': patch +--- + +`CodeDiff` with a file header now shows its lines flush against the header and the card's bottom edge, so stacked diffs in a `CodeDiffList` read like a pull request with no blank band above the first line or below the last. The horizontal scrollbar only takes room when lines overflow, and none on platforms with overlay scrollbars. Diffs without a header keep their padding. diff --git a/docs/src/content/en/integrations/observability/opentelemetry.mdx b/docs/src/content/en/integrations/observability/opentelemetry.mdx index d2527be1ca8..3c72c571eda 100644 --- a/docs/src/content/en/integrations/observability/opentelemetry.mdx +++ b/docs/src/content/en/integrations/observability/opentelemetry.mdx @@ -13,13 +13,13 @@ Mastra supports OpenTelemetry (OTEL) through an exporter for sending traces and ## Exporter -The OpenTelemetry exporter sends your traces and logs using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, Sentry, SigNoz, MLflow, Latitude, Dash0, Traceloop, Laminar, telemetry.dev, Sazabi, Agnost AI, and more. +The OpenTelemetry exporter sends your traces and logs using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Agnost AI, Dash0, Datadog, Laminar, Latitude, MLflow, New Relic, Sazabi, Sentry, SigNoz, telemetry.dev, Traceloop, and more. ### Installation Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider: -#### For HTTP/Protobuf providers (SigNoz, New Relic, Sentry, Laminar, MLflow, Latitude, telemetry.dev, Agnost AI) +#### For HTTP/Protobuf providers (Agnost AI, Laminar, Latitude, MLflow, New Relic, Sentry, SigNoz, telemetry.dev) ```bash npm2yarn npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto @@ -31,7 +31,7 @@ npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-prot npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js ``` -#### For HTTP/JSON providers (Traceloop, Sazabi) +#### For HTTP/JSON providers (Sazabi, Traceloop) ```bash npm2yarn npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http @@ -44,129 +44,13 @@ All providers support zero-config setup via environment variables. Set the appro | Provider | Environment Variables | | - | - | | Dash0 | `DASH0_API_KEY` (required), `DASH0_ENDPOINT` (required), `DASH0_DATASET` (optional) | -| SigNoz | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional) | -| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional) | -| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) | | Laminar | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional) | +| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional) | +| SigNoz | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional) | +| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) | ### Provider configurations -#### Sentry - -[Sentry](https://sentry.io/) accepts OpenTelemetry traces and logs through its OTLP endpoints. In Sentry, open [**Project Settings** > **Client Keys (DSN)**](https://sentry.io/settings/projects/) and copy the OTLP traces endpoint and authentication header. Add both values to your environment: - -```bash title=".env" -SENTRY_OTLP_ENDPOINT=https://o000000.ingest.sentry.io/api/0000000/integration/otlp/v1/traces -SENTRY_OTLP_AUTH_HEADER="sentry sentry_key=..." -``` - -Use the `custom` provider with HTTP/Protobuf: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: process.env.SENTRY_OTLP_ENDPOINT!, - protocol: 'http/protobuf', - headers: { - 'x-sentry-auth': process.env.SENTRY_OTLP_AUTH_HEADER!, - }, - }, - }, -}) -``` - -See [Sentry's OTLP documentation](https://docs.sentry.io/concepts/otlp/) for endpoint setup, supported signals, and current ingestion limits. - -Choose an exporter based on your setup: - -- `OtelExporter`: Sends vendor-neutral traces and logs over OTLP. Use it with an existing OpenTelemetry pipeline or when you want backend portability. -- [`SentryExporter`](/integrations/observability/sentry): Uses the Sentry SDK to map Mastra span types to Sentry operations, add AI monitoring attributes, and capture span errors as Sentry issues. - -#### MLflow - -[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces are routed to the correct MLflow experiment: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`, - protocol: 'http/protobuf', - headers: { - 'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID, - }, - }, - }, -}) -``` - -#### Latitude - -[Latitude](https://latitude.so) is an open-source LLM observability and evaluation platform that ingests OTLP traces. Use the `custom` provider with HTTP/Protobuf, pointing at Latitude's ingestion endpoint and authenticating with your API key and project slug: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: 'https://ingest.latitude.so/v1/traces', - protocol: 'http/protobuf', - headers: { - Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`, - 'X-Latitude-Project': process.env.LATITUDE_PROJECT, - }, - }, - }, -}) -``` - -Sign up at [console.latitude.so](https://console.latitude.so/login), or self-host and point the endpoint at your own ingestion host. - -#### telemetry.dev - -[telemetry.dev](https://telemetry.dev) ingests OTLP/HTTP protobuf traces and normalizes OpenTelemetry GenAI semantic conventions into model, provider, token, latency, and cost fields. Use the `custom` provider with your project API key: - -```bash title=".env" -TELEMETRY_DEV_API_KEY=td_live_... -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: 'https://ingest.telemetry.dev/v1/traces', - protocol: 'http/protobuf', - headers: { - Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`, - }, - }, - }, -}) -``` - -#### Sazabi - -[Sazabi](https://sazabi.com) is an AI-native observability platform that ingests OTLP traces. In Sazabi, add a Mastra log source and copy its intake URL. The URL carries your project key, so no auth header is needed: - -```bash title=".env" -SAZABI_INTAKE_URL=https://... -``` - -Use the `custom` provider with HTTP/JSON: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: process.env.SAZABI_INTAKE_URL!, - protocol: 'http/json', - }, - }, -}) -``` - -See [Sazabi's Mastra guide](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/mastra) for the full setup. - #### Agnost AI [Agnost AI](https://agnost.ai) ingests OTLP/HTTP protobuf traces and groups them into conversations and users for production agent monitoring. Use the `custom` provider with your organization ID: @@ -265,138 +149,6 @@ Get your Dash0 endpoint from your dashboard. It should be in the format `ingress ::: -#### `SigNoz` - -[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support. - -##### Zero-Config Setup - -```bash title=".env" -# Required -SIGNOZ_API_KEY=your-api-key - -# Optional -SIGNOZ_REGION=us # 'us' | 'eu' | 'in' -SIGNOZ_ENDPOINT=https://my-signoz.example.com # For self-hosted -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { signoz: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - signoz: { - apiKey: process.env.SIGNOZ_API_KEY, - region: 'us', // 'us' | 'eu' | 'in' - // endpoint: 'https://my-signoz.example.com', // For self-hosted - }, - }, -}) -``` - -#### New Relic - -[New Relic](https://newrelic.com/) provides complete observability with AI monitoring capabilities. - -##### Zero-Config Setup - -```bash title=".env" -# Required -NEW_RELIC_LICENSE_KEY=your-license-key - -# Optional -NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net # For EU region -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { newrelic: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - newrelic: { - apiKey: process.env.NEW_RELIC_LICENSE_KEY, - // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region - }, - }, -}) -``` - -#### Traceloop - -[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking. - -##### Zero-Config Setup - -```bash title=".env" -# Required -TRACELOOP_API_KEY=your-api-key - -# Optional -TRACELOOP_DESTINATION_ID=my-destination -TRACELOOP_ENDPOINT=https://custom.traceloop.com -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { traceloop: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - traceloop: { - apiKey: process.env.TRACELOOP_API_KEY, - destinationId: 'my-destination', // Optional - }, - }, -}) -``` - -#### Laminar - -[Laminar](https://laminar.sh/) provides specialized LLM observability and analytics. - -##### Zero-Config Setup - -```bash title=".env" -# Required -LMNR_PROJECT_API_KEY=your-api-key - -# Optional -LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { laminar: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - laminar: { - apiKey: process.env.LMNR_PROJECT_API_KEY, - }, - }, -}) -``` - -:::tip Laminar-Native Exporter - -For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](/integrations/observability/laminar) exporter instead. It provides optimized integration with Laminar's platform. - -::: - #### Datadog [Datadog](https://www.datadoghq.com/) APM provides application performance monitoring with distributed tracing. To send traces to Datadog via OTLP, you need the Datadog Agent running with OTLP ingestion enabled. @@ -465,6 +217,254 @@ For Datadog-specific features like automatic span type mapping, LLM span categor ::: +#### Laminar + +[Laminar](https://laminar.sh/) provides specialized LLM observability and analytics. + +##### Zero-Config Setup + +```bash title=".env" +# Required +LMNR_PROJECT_API_KEY=your-api-key + +# Optional +LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { laminar: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + laminar: { + apiKey: process.env.LMNR_PROJECT_API_KEY, + }, + }, +}) +``` + +:::tip Laminar-Native Exporter + +For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](/integrations/observability/laminar) exporter instead. It provides optimized integration with Laminar's platform. + +::: + +#### Latitude + +[Latitude](https://latitude.so) is an open-source LLM observability and evaluation platform that ingests OTLP traces. Use the `custom` provider with HTTP/Protobuf, pointing at Latitude's ingestion endpoint and authenticating with your API key and project slug: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: 'https://ingest.latitude.so/v1/traces', + protocol: 'http/protobuf', + headers: { + Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`, + 'X-Latitude-Project': process.env.LATITUDE_PROJECT, + }, + }, + }, +}) +``` + +Sign up at [console.latitude.so](https://console.latitude.so/login), or self-host and point the endpoint at your own ingestion host. + +#### MLflow + +[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces are routed to the correct MLflow experiment: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`, + protocol: 'http/protobuf', + headers: { + 'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID, + }, + }, + }, +}) +``` + +#### New Relic + +[New Relic](https://newrelic.com/) provides complete observability with AI monitoring capabilities. + +##### Zero-Config Setup + +```bash title=".env" +# Required +NEW_RELIC_LICENSE_KEY=your-license-key + +# Optional +NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net # For EU region +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { newrelic: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + newrelic: { + apiKey: process.env.NEW_RELIC_LICENSE_KEY, + // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region + }, + }, +}) +``` + +#### Sazabi + +[Sazabi](https://sazabi.com) is an AI-native observability platform that ingests OTLP traces. In Sazabi, add a Mastra log source and copy its intake URL. The URL carries your project key, so no auth header is needed: + +```bash title=".env" +SAZABI_INTAKE_URL=https://... +``` + +Use the `custom` provider with HTTP/JSON: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: process.env.SAZABI_INTAKE_URL!, + protocol: 'http/json', + }, + }, +}) +``` + +See [Sazabi's Mastra guide](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/mastra) for the full setup. + +#### Sentry + +[Sentry](https://sentry.io/) accepts OpenTelemetry traces and logs through its OTLP endpoints. In Sentry, open [**Project Settings** > **Client Keys (DSN)**](https://sentry.io/settings/projects/) and copy the OTLP traces endpoint and authentication header. Add both values to your environment: + +```bash title=".env" +SENTRY_OTLP_ENDPOINT=https://o000000.ingest.sentry.io/api/0000000/integration/otlp/v1/traces +SENTRY_OTLP_AUTH_HEADER="sentry sentry_key=..." +``` + +Use the `custom` provider with HTTP/Protobuf: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: process.env.SENTRY_OTLP_ENDPOINT!, + protocol: 'http/protobuf', + headers: { + 'x-sentry-auth': process.env.SENTRY_OTLP_AUTH_HEADER!, + }, + }, + }, +}) +``` + +See [Sentry's OTLP documentation](https://docs.sentry.io/concepts/otlp/) for endpoint setup, supported signals, and current ingestion limits. + +Choose an exporter based on your setup: + +- `OtelExporter`: Sends vendor-neutral traces and logs over OTLP. Use it with an existing OpenTelemetry pipeline or when you want backend portability. +- [`SentryExporter`](/integrations/observability/sentry): Uses the Sentry SDK to map Mastra span types to Sentry operations, add AI monitoring attributes, and capture span errors as Sentry issues. + +#### SigNoz + +[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support. + +##### Zero-Config Setup + +```bash title=".env" +# Required +SIGNOZ_API_KEY=your-api-key + +# Optional +SIGNOZ_REGION=us # 'us' | 'eu' | 'in' +SIGNOZ_ENDPOINT=https://my-signoz.example.com # For self-hosted +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { signoz: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + signoz: { + apiKey: process.env.SIGNOZ_API_KEY, + region: 'us', // 'us' | 'eu' | 'in' + // endpoint: 'https://my-signoz.example.com', // For self-hosted + }, + }, +}) +``` + +#### telemetry.dev + +[telemetry.dev](https://telemetry.dev) ingests OTLP/HTTP protobuf traces and normalizes OpenTelemetry GenAI semantic conventions into model, provider, token, latency, and cost fields. Use the `custom` provider with your project API key: + +```bash title=".env" +TELEMETRY_DEV_API_KEY=td_live_... +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: 'https://ingest.telemetry.dev/v1/traces', + protocol: 'http/protobuf', + headers: { + Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`, + }, + }, + }, +}) +``` + +#### Traceloop + +[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking. + +##### Zero-Config Setup + +```bash title=".env" +# Required +TRACELOOP_API_KEY=your-api-key + +# Optional +TRACELOOP_DESTINATION_ID=my-destination +TRACELOOP_ENDPOINT=https://custom.traceloop.com +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { traceloop: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + traceloop: { + apiKey: process.env.TRACELOOP_API_KEY, + destinationId: 'my-destination', // Optional + }, + }, +}) +``` + #### Custom/Generic OTEL Endpoints For other OTEL-compatible platforms or custom collectors: @@ -525,7 +525,7 @@ If the matching log exporter package isn't installed, log export is silently dis new OtelExporter({ // Provider configuration (required) provider: { - // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom + // Use one of: dash0, laminar, newrelic, signoz, traceloop, custom }, // Per-signal toggles. Both default to true. @@ -577,10 +577,10 @@ Choose the right protocol package based on your provider: | - | - | - | | Dash0 | gRPC | `@opentelemetry/exporter-trace-otlp-grpc` | | Datadog | gRPC | `@opentelemetry/exporter-trace-otlp-grpc` | -| SigNoz | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | -| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | -| Traceloop | HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` | | Laminar | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | +| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | +| SigNoz | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | +| Traceloop | HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` | | Custom | Varies | Depends on your collector | :::warning diff --git a/docs/src/content/en/reference/agents/durable-agent.mdx b/docs/src/content/en/reference/agents/durable-agent.mdx index 5e7bf3a0aea..b381f2a9544 100644 --- a/docs/src/content/en/reference/agents/durable-agent.mdx +++ b/docs/src/content/en/reference/agents/durable-agent.mdx @@ -440,7 +440,7 @@ Returns: `boolean`. `true` when this process aborted the run locally or can see #### `abortThreadStream({ threadId, resourceId?, expectedRunId? })` -Aborts the active run on a memory thread with the same abort request as `abortRunStream()`. The run is resolved from this process's thread runtime, so it must have been started here or observed through `subscribeToThread()` on this process. The server route `POST /agents/:agentId/threads/abort` uses this method. +Aborts the active run on a memory thread with the same abort request as `abortRunStream()`. When this process runs the thread's active run, the abort applies here. When this process has observed the run through `subscribeToThread()`, the abort request is published to the process executing the run, and nothing stops in this process. When the process never saw the run, it looks the run up in the background through the thread's lease and asks the process executing it to stop, publishing the request over the shared PubSub. That lookup runs asynchronously. The method returns before the lookup finishes. The server route [`POST /agents/:agentId/threads/abort`](/reference/server/routes#thread-cancellation-routes) awaits the lookup when the abort wasn't resolved in this process, which is how it reports whether a run on another process was asked to stop. Pass `expectedRunId` when the request must only stop a specific run. If another queued run becomes active before the request is handled, the method returns `false` without aborting the successor. Omit `expectedRunId` to abort whichever run is active when the request is handled. @@ -452,7 +452,7 @@ const aborted = durableAgent.abortThreadStream({ }) ``` -Returns: `boolean`. `false` when this process has no active run recorded for the thread or the active run doesn't match `expectedRunId`. No abort request is sent in either case. +Returns: `boolean`. `true` when this process aborted the run, or when the abort request was published to the process executing it. A published request doesn't confirm that the other process stopped the run. `false` is this process's own result: it had no run of the thread's to stop, the active run didn't match `expectedRunId`, or `localOnly: true` kept the abort local and left a run owned by another process alone. An `expectedRunId` mismatch and `localOnly: true` leave the run running by design. Otherwise `false` doesn't rule out a forwarded abort: the background lookup still publishes an abort request to the process holding the lease when it finishes, or finds nothing to publish. A failed lookup or publish is logged as a warning through the Mastra logger. Use the thread-abort route above when you need the forwarded outcome reported. ### Recovery diff --git a/docs/src/content/en/reference/client-js/mastra-client.mdx b/docs/src/content/en/reference/client-js/mastra-client.mdx index 1c34280cd35..9de478a891e 100644 --- a/docs/src/content/en/reference/client-js/mastra-client.mdx +++ b/docs/src/content/en/reference/client-js/mastra-client.mdx @@ -56,7 +56,7 @@ You can also pass `requestContext` as a `Record`. name: 'retries', type: 'number', description: - "The number of times a request will be retried on failure before throwing an error. Retries apply to read requests (GET, HEAD, OPTIONS) by default, and to the observability queries that read server state even though they are sent as POST (aggregateTraces, aggregateSpans, queryTraceThreads, querySpans). Write requests (POST, PUT, PATCH, DELETE) are sent once unless you set this explicitly, so a server error can't repeat a state-changing request.", + "The number of times a request will be retried on failure before throwing an error. Retries apply to read requests (GET, HEAD, OPTIONS) by default, and to the observability queries that read server state even though they are sent as POST (aggregateTraces, aggregateSpans, queryTraceThreads, querySpans). Write requests (POST, PUT, PATCH, DELETE) are sent once unless you set `retries` here, so a server error can't repeat a state-changing request. Methods that accept request options, such as `createFeedback()` and `replaceFeedback()`, can also set `retries` per call, and that count takes precedence over this one. This count covers transport retries only: `createScore()`, `createFeedback()`, and `replaceFeedback()` also retry missing-trace and missing-span responses for up to 30 seconds unless you pass `anchorRetryTimeoutMs: 0`, as described in the observability reference under Signal write options.", isOptional: true, defaultValue: '3 for read requests, 0 for write requests', }, diff --git a/docs/src/content/en/reference/client-js/observability.mdx b/docs/src/content/en/reference/client-js/observability.mdx index e2d9ab0ce00..9940a39181c 100644 --- a/docs/src/content/en/reference/client-js/observability.mdx +++ b/docs/src/content/en/reference/client-js/observability.mdx @@ -520,7 +520,7 @@ await mastraClient.replaceFeedback({ }) ``` -Use the normalized timestamp from the create response's `data` when available. OSS rejects changes to the original trace or timestamp with `409`. Platform uses the timestamp as part of record identity, so preserve it there too. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable automatic retries. +Use the normalized timestamp from the create response's `data` when available. OSS rejects changes to the original trace or timestamp with `409`. Platform uses the timestamp as part of record identity, so preserve it there too. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. PUT requests get no transport retries by default, but a client configured with `retries` applies that count here too, and anchor retries stay on unless you turn them off. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable both transport and anchor retries. `retries: 0` is only redundant when the client has no `retries` configured. ### Deleting feedback and scores diff --git a/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx b/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx index 4e3daecbbb1..3797602c7b4 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx +++ b/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx @@ -1,4 +1,11 @@ -import { NotificationActivity } from '@mastra/playground-ui/components/ai/activity'; +import { + Activity, + ActivityHeader, + ActivityIcon, + ActivityLabel, + NotificationActivity, +} from '@mastra/playground-ui/components/ai/activity'; +import { Badge } from '@mastra/playground-ui/components/Badge'; import { Button } from '@mastra/playground-ui/components/Button'; import { Txt } from '@mastra/playground-ui/components/Txt'; import { cn } from '@mastra/playground-ui/utils/cn'; @@ -162,8 +169,46 @@ function WaitingSessionActions({ factoryId, waiting }: { factoryId: string; wait ); } +const NOTIFICATION_SOURCE_NAMES: Record = { + 'factory-session': 'Factory session', + github: 'GitHub', + gitlab: 'GitLab', + linear: 'Linear', + jira: 'Jira', + slack: 'Slack', +}; + +/** A readable name for a notification source; unknown sources fall back to their id in sentence case. */ +export function notificationSourceName(source: string): string { + if (Object.hasOwn(NOTIFICATION_SOURCE_NAMES, source)) return NOTIFICATION_SOURCE_NAMES[source]; + const words = source.replace(/[-_]+/g, ' ').trim(); + return words ? words.charAt(0).toUpperCase() + words.slice(1) : source; +} + export function NotificationSummaryCard({ entry }: { entry: NotificationSummaryEntry }) { - return ; + const sources = Object.entries(entry.bySource).filter(([, count]) => count > 0); + const counted = entry.pending > 0 && sources.length > 0; + const urgent = (entry.byPriority.urgent ?? 0) > 0 || (entry.byPriority.high ?? 0) > 0; + + return ( + + + + + + Notifications + + {counted ? `${entry.pending} new` : entry.message} + + {counted && + sources.map(([source, count]) => ( + + {sources.length > 1 ? `${notificationSourceName(source)} ${count}` : notificationSourceName(source)} + + ))} + + + ); } export function notificationMetadata(entry: MessageEntry): Array { diff --git a/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx index f84f8327594..7196cd9da9e 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx @@ -56,22 +56,80 @@ describe('Transcript notifications', () => { }); describe('when pending notifications are summarized', () => { - it('puts the summary in the transcript under its own label', () => { + it('says how many are new and names their source', () => { renderEntries([ { kind: 'notification_summary', id: 'summary', - message: '2 pull requests and 1 issue need attention.', - pending: 3, - bySource: { github: 3 }, - byPriority: { high: 3 }, - notificationIds: ['1', '2', '3'], + message: 'factory-session: 1', + pending: 1, + bySource: { 'factory-session': 1 }, + byPriority: { low: 1 }, + notificationIds: ['1'], }, ]); - const notification = within(screen.getByRole('group', { name: 'Notification: Notification summary' })); - expect(notification.getByText('2 pull requests and 1 issue need attention.')).toBeVisible(); - expect(notification.queryByRole('button')).not.toBeInTheDocument(); + const summary = screen.getByRole('group', { name: 'Notification summary' }); + expect(summary).toHaveAttribute('data-notification-state', 'summary'); + expect(within(summary).getByText('Notifications')).toBeVisible(); + expect(within(summary).getByText('1 new')).toBeVisible(); + expect(within(summary).getByText('Factory session')).toBeVisible(); + expect(within(summary).queryByText('factory-session: 1')).not.toBeInTheDocument(); + expect(within(summary).queryByRole('button')).not.toBeInTheDocument(); + }); + + it('counts each source when several are pending, including ones it has no name for', () => { + renderEntries([ + { + kind: 'notification_summary', + id: 'summary', + message: 'github: 3, my-webhook: 1', + pending: 4, + bySource: { github: 3, 'my-webhook': 1 }, + byPriority: { high: 3, low: 1 }, + notificationIds: ['1', '2', '3', '4'], + }, + ]); + + const summary = within(screen.getByRole('group', { name: 'Notification summary' })); + expect(summary.getByText('4 new')).toBeVisible(); + expect(summary.getByText('GitHub 3')).toBeVisible(); + expect(summary.getByText('My webhook 1')).toBeVisible(); + }); + + it('falls back to the summary text when it carries no counts', () => { + renderEntries([ + { + kind: 'notification_summary', + id: 'summary', + message: 'No pending notifications', + pending: 0, + bySource: {}, + byPriority: {}, + notificationIds: [], + }, + ]); + + const summary = within(screen.getByRole('group', { name: 'Notification summary' })); + expect(summary.getByText('No pending notifications')).toBeVisible(); + }); + + it('names a source that collides with a built-in object key from its id', () => { + renderEntries([ + { + kind: 'notification_summary', + id: 'summary', + message: '__proto__: 1', + pending: 1, + bySource: JSON.parse('{"__proto__": 1}') as Record, + byPriority: { low: 1 }, + notificationIds: ['1'], + }, + ]); + + const summary = within(screen.getByRole('group', { name: 'Notification summary' })); + expect(summary.getByText('1 new')).toBeVisible(); + expect(summary.getByText('Proto')).toBeVisible(); }); }); }); diff --git a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css index f7ddb710e59..e1a83211f0d 100644 --- a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css +++ b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css @@ -12,3 +12,10 @@ --diffs-bg-separator-override: var(--muted); --diffs-fg-number-override: var(--placeholder); } + +/* Under a file header the lines run flush from the header to the card's bottom edge, like a pull request. + The horizontal scrollbar only takes room when lines overflow. */ +.code-diff[data-header] { + --diffs-gap-block: 0px; + --diffs-overflow-override: auto; +} diff --git a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx index 69ebe8f8d51..f469a21ce05 100644 --- a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx +++ b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx @@ -97,7 +97,11 @@ export function CodeDiff({ className, layout, overflow = 'wrap', header, ref, .. }; return ( -
+
{header ? (