@sentry/cloudflare 10.69.0 → 10.70.0

package/build/types-ts3.8/instrumentations/agents/index.d.ts

@@ -4,9 +4,10 @@
  *
  * - **Callable RPC spans** — a span (op `rpc`) for each `@callable()` method invoked over WebSocket.
  * - **Conversation correlation** — sets the conversation id on the scope for each unit of agent
- *   work — chat turn or callable RPC call — so `gen_ai` spans created within it are correlated, for
- *   chat and plain agents alike. Defaults to the instance `name` and is rotated when the chat is
- *   cleared (the `message:clear` observability event).
+ *   work — chat turn, callable RPC call, or HTTP request — so `gen_ai` spans created within it are
+ *   correlated, for chat and plain agents alike. The id is minted once per agent instance and
+ *   rotated when the chat is cleared (the `message:clear` observability event); it is persisted to
+ *   Durable Object storage so it survives hibernation.
  *
  * It only hooks the `agents` package internals and uses Sentry's tracing primitives. On Cloudflare
  * Workers, prefer `instrumentAgentWithSentry`, which additionally instruments the Durable Object

package/build/types-ts3.8/instrumentations/agents/instrumentAgentCallableRpc.d.ts

@@ -5,7 +5,10 @@ import { AgentInternals } from './types';
  * the WebSocket message (on Cloudflare, the instrumented Durable Object `webSocketMessage` hook).
  *
  * Also sets the conversation id on the scope for the duration of the call: callable methods are the
- * unit of work for plain (non-chat) agents, which run LLM calls just like chat turns do.
+ * unit of work for plain (non-chat) agents, which run LLM calls just like chat turns do. It is
+ * awaited so the id is on the scope before the method body creates any span; the `agents`
+ * `onMessage` own property this wraps is already `async`, so the promise return is nothing new to
+ * the WebSocket dispatch upstream.
  */
 export declare function instrumentAgentCallableRpc(obj: AgentInternals): void;
 //# sourceMappingURL=instrumentAgentCallableRpc.d.ts.map

package/build/types-ts3.8/instrumentations/agents/instrumentAgentRequestConversation.d.ts

@@ -0,0 +1,16 @@
+import { AgentInternals } from './types';
+/**
+ * Correlates the AI spans of an HTTP-driven agent turn with a conversation id on the active scope.
+ *
+ * `onRequest` is the third unit of agent work, alongside chat turns and `@callable()` RPC: the
+ * `agents` router sends every non-WebSocket request to it, which is how REST endpoints and webhooks
+ * reach an agent.
+ *
+ * `agents` installs `onRequest` as an own property in the `Agent` constructor (as it does
+ * `onMessage`), and we instrument after construction, so wrapping the own property is what the
+ * router ends up calling. That own property is already `async`, and partyserver's `fetch` awaits it,
+ * so returning a promise from this wrapper — to get the conversation id onto the scope before the
+ * request handler creates any span — keeps the existing contract.
+ */
+export declare function instrumentAgentRequestConversation(obj: AgentInternals): void;
+//# sourceMappingURL=instrumentAgentRequestConversation.d.ts.map

package/build/types-ts3.8/instrumentations/agents/instrumentChatAgentConversation.d.ts

@@ -3,16 +3,17 @@ import { AgentInternals } from './types';
  * For chat agents (`AIChatAgent` from `@cloudflare/ai-chat`), correlates each chat turn's AI spans
  * with a conversation id on the active scope.
  *
- * In the Agents model one agent instance is one long-lived conversation, so the instance `name` is
- * the base conversation id. When the user clears the chat, they expect a fresh conversation — but
- * recreating the Durable Object for that would also drop the MCP/OAuth state stored per instance
- * (GitHub/Sentry sign-in). To get a fresh conversation id *without* losing that state, we rotate an
- * in-memory id on the instance when the SDK reports a cleared chat, and stamp that (falling back to
- * the instance `name` before the first clear).
+ * In the Agents model one agent instance is one long-lived conversation, so the conversation id is
+ * minted once per instance and persisted to Durable Object storage, which is what carries it across
+ * hibernation (that destroys the in-memory instance). When the user clears the chat, they expect a
+ * fresh conversation — but recreating the Durable Object for that would also drop the MCP/OAuth
+ * state stored per instance (GitHub/Sentry sign-in). To get a fresh conversation id *without*
+ * losing that state, we rotate the persisted id when the SDK reports a cleared chat.
  *
- * The id itself is not attached to spans here — the SDK's `conversationIdIntegration` reads it off
- * the scope at `spanStart` and stamps `gen_ai.conversation.id` onto the AI spans created inside the
- * turn (e.g. by the Workers AI instrumentation), which correlates a turn's model and tool calls.
+ * The id itself is not attached to spans here — `setAgentConversationId` resolves it, and the SDK's
+ * `conversationIdIntegration` picks it off the scope at `spanStart` to stamp
+ * `gen_ai.conversation.id` onto the AI spans created inside the turn (e.g. by the Workers AI
+ * instrumentation), which correlates a turn's model and tool calls.
  *
  * Plain (non-chat) `Agent`s do not define `onChatMessage`, so they are skipped here — their unit
  * of work is the callable RPC method, where `instrumentAgentCallableRpc` sets the conversation id

package/build/types-ts3.8/instrumentations/agents/types.d.ts

@@ -1,6 +1,14 @@
+import { InstrumentedDurableObjectState } from '../../wrapMethodWithSentry';
 export declare const AGENT_SPAN_ORIGIN = "auto.faas.cloudflare.agents";
-export declare const AGENT_CLASS_ATTRIBUTE = "cloudflare.agent.class";
-export declare const AGENT_NAME_ATTRIBUTE = "cloudflare.agent.name";
+/** DO storage key under which the conversation id is persisted so it survives hibernation. */
+export declare const AGENT_CONVERSATION_ID_STORAGE_KEY = "__SENTRY_AGENT_CONVERSATION_ID__";
+/**
+ * Instance keys for our conversation-id bookkeeping, keyed by symbol so the state stays invisible
+ * to anything enumerating the user-owned agent instance (`Object.keys`, `JSON.stringify`, spread).
+ * Exported because the exported `AgentInternals` interface references them.
+ */
+export declare const AGENT_CONVERSATION_ID_SYMBOL: unique symbol;
+export declare const AGENT_APPLIED_CONVERSATION_ID_SYMBOL: unique symbol;
 /**
  * The subset of the `agents` `Agent` instance internals that we instrument. These are runtime
  * implementation details of the `agents` package (v0.13.x) rather than part of its public type
@@ -16,34 +24,71 @@ export interface AgentInternals {
      * does not, so its presence discriminates a chat agent.
      */
     onChatMessage?: (...args: unknown[]) => unknown;
+    /** HTTP request handler; the router sends every non-WebSocket request here. */
+    onRequest?: (...args: unknown[]) => unknown;
     /** The user's Agent class (used by the SDK for the observability event `agent` field). */
     _ParentClass?: {
         name?: string;
     };
-    /** The Agent instance name, which in the Agents model identifies the conversation/thread. */
+    /** The Agent instance name, reported as the `cloudflare.agent.name` span attribute. */
     name?: string;
     /**
-     * Internal: the active conversation id, rotated when the chat is cleared (the `message:clear`
-     * observability event) so a reset chat groups as a fresh conversation while the instance (and its
-     * MCP/OAuth state) stays put. Set by `instrumentChatAgentConversation`; falls back to `name`
-     * before the first clear.
+     * The Durable Object state of the instance. Present on every real Agent; guarded like the other
+     * internals so partially-mocked instances keep working.
+     */
+    ctx?: InstrumentedDurableObjectState;
+    /**
+     * The current conversation id for this agent instance. It is cached in memory after being loaded
+     * from Durable Object storage and updated when the conversation rotates. `undefined` means storage
+     * has not been read yet.
+     */
+    [AGENT_CONVERSATION_ID_SYMBOL]?: string;
+    /**
+     * The conversation id this instrumentation most recently applied to the isolation scope. It lets
+     * subsequent units of work distinguish an SDK-applied id, which may be replaced after rotation,
+     * from an id explicitly set by the user, which must be preserved.
      */
-    __sentryConversationId?: string;
+    [AGENT_APPLIED_CONVERSATION_ID_SYMBOL]?: string;
 }
 /** Reads best-effort agent identity attributes from the instance, tolerating missing internals. */
 export declare function getAgentAttributes(instance: AgentInternals): Record<string, string>;
 /**
- * Sets the agent instance's conversation id on the current scope for the duration of the
- * surrounding unit of work (chat turn, callable RPC call). In the Agents model one instance is one
- * conversation, so the instance `name` is the natural conversation id — for chat and plain agents
- * alike, since plain agents run LLM calls too (e.g. inside `@callable()` methods). Once the chat
- * has been cleared, the rotated `__sentryConversationId` takes precedence so LLM calls from any
- * unit of work group under the fresh conversation.
+ * Persists the conversation id to Durable Object storage, so it survives hibernation, and updates
+ * the in-memory cache synchronously so the current wake is immediately consistent even if the
+ * write fails. Uses the async storage API, which exists on KV- and SQLite-backed DOs alike.
+ * The write is fire-and-forget: DO storage writes are tracked by the runtime and land without
+ * awaiting (`waitUntil` is a no-op in Durable Objects), and the catch keeps a rejection from
+ * surfacing as unhandled — a failed write just means the next wake starts a new conversation,
+ * which must never throw into user code. Uses the original uninstrumented storage so internal
+ * bookkeeping doesn't create spans.
+ */
+export declare function storeAgentConversationId(instance: AgentInternals, conversationId: string): void;
+/**
+ * Sets the agent instance's conversation id on the active scope for the duration of the
+ * surrounding unit of work (chat turn, callable RPC call, HTTP request). In the Agents model one
+ * instance is one long-lived conversation, so the id is minted once per instance and persisted to
+ * DO storage — for chat and plain agents alike, since plain agents run LLM calls too (e.g. inside
+ * `@callable()` methods). The instance `name` is deliberately not used: it is caller-chosen and can
+ * be a stable, guessable, or shared value, whereas a conversation id should identify exactly one
+ * conversation. Clearing the chat rotates it (see `storeAgentConversationId`) so subsequent LLM
+ * calls group under the fresh conversation.
+ *
+ * Every handler wrapper awaits this before invoking the original, so the id is on the scope before
+ * the unit of work — and any `gen_ai` span it creates — starts. Only the first unit of work per wake
+ * pays the storage read; the rest resolve from the in-memory cache. Awaiting is safe on all three
+ * paths because the `agents` `Agent` constructor already replaces `onMessage` and `onRequest` with
+ * `async` wrappers of its own, and `onChatMessage` is async by contract, so every caller upstream
+ * already handles a promise.
+ *
+ * An id the user set explicitly outranks this inferred one, in either order: a `setConversationId()`
+ * call that already happened is detected here and left alone, and one made inside the handler lands
+ * on the same scope afterwards and therefore wins. That is why the write targets the isolation scope
+ * — it is the scope the public `Sentry.setConversationId()` writes to, and `conversationIdIntegration`
+ * prefers the current scope over it, so writing there would make a user's call unoverridable.
  *
  * `conversationIdIntegration` reads the id off the scope at `spanStart` and stamps
- * `gen_ai.conversation.id` onto AI spans created within the unit of work, correlating its model
- * and tool calls. Callers run inside a per-event forked scope (`wrapMethodWithSentry`), so the id
- * does not leak into unrelated events.
+ * `gen_ai.conversation.id` onto AI spans created within the unit of work, correlating its model and
+ * tool calls.
  */
-export declare function setAgentConversationId(instance: AgentInternals): void;
+export declare function setAgentConversationId(instance: AgentInternals): Promise<void>;
 //# sourceMappingURL=types.d.ts.map

package/build/types-ts3.8/utils/invocationScope.d.ts

@@ -0,0 +1,24 @@
+import { Scope } from '@sentry/core';
+/**
+ * Runs `callback` on the isolation scope for the current invocation.
+ *
+ * An instrumented handler is either the entry point of an invocation or reentrant — reached from
+ * another instrumented handler already serving the same invocation (a Durable Object method calling
+ * its own `fetch`, an RPC method reaching a sibling method). Only the entry point may fork:
+ *
+ * - Forking at the entry point is mandatory. `setUser`/`setTag` write to the isolation scope, and a
+ *   Durable Object's isolation scope outlives the invocation that touched it, so without a fork one
+ *   invocation's user and tags reappear on the next invocation's events in the same isolate.
+ *   Forking clones, so request data set by an enclosing wrapper is still inherited.
+ * - Forking again when reentrant would be wrong. Everything below the entry point is one logical
+ *   unit of work: a nested call must see what the caller set and be able to add to it, the way it
+ *   would if the SDK were not wrapping it at all.
+ *
+ * The AsyncLocalStorage strategy hands the default isolation scope back whenever no invocation is in
+ * flight, and a forked one while inside `withIsolationScope`. Reference-comparing against the default
+ * is therefore enough to tell the two cases apart. The stack fallback does not fork, so it reports the
+ * default scope even inside an invocation; there the fork degrades to a no-op, which the stack strategy
+ * tolerates. This matches the approach used by `patchEventHandler` in Nuxt.
+ */
+export declare function withInvocationIsolationScope<T>(callback: (scope: Scope) => T): T;
+//# sourceMappingURL=invocationScope.d.ts.map

package/build/types-ts3.8/utils/rpcMeta.d.ts

@@ -4,6 +4,14 @@ import { SerializedTraceData } from '@sentry/core';
  * If no active trace exists, returns the original args unchanged.
  */
 export declare function appendRpcMeta(args: unknown[]): unknown[];
+/**
+ * Whether the trailing argument carries Sentry RPC metadata.
+ *
+ * Separate from {@link extractRpcMeta} because the RPC method wrappers run this check on every
+ * call — including the instance's own internal method calls, which never carry metadata — and
+ * must not allocate on that path.
+ */
+export declare function hasRpcMeta(args: unknown[]): boolean;
 /**
  * Extracts Sentry RPC metadata from the trailing argument of an args array.
  * Returns cleaned args (without meta) and the extracted trace data if found.

package/build/types-ts3.8/wrapMethodWithSentry.d.ts

@@ -1,7 +1,7 @@
 import { DurableObjectStorage } from '@cloudflare/workers-types';
 import { CloudflareOptions } from './client';
 /** Extended DurableObjectState with originalStorage exposed by instrumentContext */
-interface InstrumentedDurableObjectState extends DurableObjectState {
+export interface InstrumentedDurableObjectState extends DurableObjectState {
     originalStorage?: DurableObjectStorage;
 }
 type MethodWrapperOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/cloudflare",
-  "version": "10.69.0",
+  "version": "10.70.0",
   "description": "Official Sentry SDK for Cloudflare Workers and Pages",
   "repository": "git://github.com/getsentry/sentry-javascript.git",
   "homepage": "https://github.com/getsentry/sentry-javascript/tree/master/packages/cloudflare",
@@ -70,8 +70,8 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@sentry/core": "10.69.0",
-    "@sentry/server-utils": "10.69.0",
+    "@sentry/core": "10.70.0",
+    "@sentry/server-utils": "10.70.0",
     "magic-string": "~0.30.21"
   },
   "peerDependencies": {