@sentry/cloudflare 10.68.0 → 10.70.0

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

@@ -0,0 +1,94 @@
+import { InstrumentedDurableObjectState } from '../../wrapMethodWithSentry';
+export declare const AGENT_SPAN_ORIGIN = "auto.faas.cloudflare.agents";
+/** 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
+ * surface, so every access is guarded and wrapping degrades gracefully if a name changes upstream.
+ */
+export interface AgentInternals {
+    /** Central choke-point through which all `agents:*` observability events are published. */
+    _emit?: (type: string, payload?: Record<string, unknown>) => void;
+    /** WebSocket message handler; dispatches `@callable()` RPC requests. */
+    onMessage?: (...args: unknown[]) => unknown;
+    /**
+     * Chat-turn handler. Only `AIChatAgent` (from `@cloudflare/ai-chat`) defines this; a plain `Agent`
+     * 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, reported as the `cloudflare.agent.name` span attribute. */
+    name?: string;
+    /**
+     * 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.
+     */
+    [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>;
+/**
+ * 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.
+ */
+export declare function setAgentConversationId(instance: AgentInternals): Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/build/types-ts3.8/integrations/spotlight.d.ts

@@ -0,0 +1,22 @@
+type SpotlightConnectionOptions = {
+    /**
+     * Set this if the Spotlight Sidecar is not running on localhost:8969.
+     * By default, the URL is set to http://localhost:8969/stream
+     */
+    sidecarUrl?: string;
+};
+export declare const INTEGRATION_NAME: "Spotlight";
+/**
+ * Use this integration to send errors and transactions to Spotlight.
+ *
+ * Learn more about spotlight at https://spotlightjs.com
+ *
+ * Important: This integration is intended for local development only.
+ * Each forwarded envelope counts as a Worker subrequest (50 free / 1000 paid
+ * per invocation), so it should not be enabled in production.
+ */
+export declare const spotlightIntegration: (options?: Partial<SpotlightConnectionOptions> | undefined) => import("@sentry/core").Integration & {
+    name: "Spotlight";
+};
+export {};
+//# sourceMappingURL=spotlight.d.ts.map

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

@@ -12,7 +12,9 @@
  *
  * The check operates on the query summary produced by `getSqlQuerySummary` (`{operation} {table} ...`,
  * the same value used as the span name), so table targets are already isolated from the rest of the
- * query.
+ * query. The one exception is `CREATE INDEX`: its summary carries the index name, not the indexed
+ * table (upstream OTel convention), so the `cf_` target only appears in the ON clause of the full
+ * statement, which `queryText` is needed for.
  */
-export declare function targetsCloudflareInternalTable(querySummary: string | undefined, allowlist?: Array<string | RegExp>): boolean;
+export declare function targetsCloudflareInternalTable(querySummary: string | undefined, allowlist?: Array<string | RegExp>, queryText?: string): boolean;
 //# sourceMappingURL=internalSqlQuery.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export declare function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean;
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export declare function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined;
+//# sourceMappingURL=internalStorageKey.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/vite/agentClass.d.ts

@@ -0,0 +1,41 @@
+import { ProgramBody } from './transform';
+/**
+ * The subset of the Vite/Rollup plugin context needed to walk the module graph.
+ *
+ * `resolve` is optional: without it detection still works, but only for base-class chains declared
+ * inside the entry module itself. `readFile` is injectable for tests and defaults to reading disk.
+ *
+ * Deliberately **no `load`**: awaiting the plugin context's `load()` from inside a `transform` hook
+ * deadlocks the build — the module cannot finish loading while its own transform is still pending
+ * (Rollup documents this hazard, and Vite's Rolldown pipeline is stricter still). Sibling modules
+ * are therefore read straight off disk; see {@link getModuleShape}.
+ */
+export interface ModuleResolver {
+    parse(code: string): ProgramBody;
+    resolve?(source: string, importer: string): Promise<{
+        id: string;
+    } | null | undefined>;
+    readFile?(id: string): string | undefined;
+}
+/**
+ * Find which of `candidates` (top-level class names in the entry module) are Cloudflare
+ * [`agents`](https://www.npmjs.com/package/agents) Agents.
+ *
+ * An Agent is a Durable Object under the hood, so wrangler configures it as one and the transform
+ * would otherwise reach for `instrumentDurableObjectWithSentry`. Detecting the Agent base chain lets
+ * it pick `instrumentAgentWithSentry` instead, which adds the Agent-specific telemetry on top.
+ *
+ * Unlike `WorkerEntrypoint` detection, the chain is followed *across* modules: base classes commonly
+ * live in their own file (`import { MyBase } from './base'`), and there is no runtime fallback that
+ * would catch a missed one. Resolution stops at package boundaries — a base class imported from
+ * `node_modules` is only recognized when it is one of {@link AGENT_BASE_CLASSES}.
+ */
+export declare function detectAgentClasses(ast: ProgramBody, entryId: string, candidates: Iterable<string>, resolver: ModuleResolver): Promise<Set<string>>;
+/**
+ * The local class names in the entry that a configured class name could refer to — either declared
+ * under that name directly, or aliased to it by an `export { Local as Configured }` specifier.
+ *
+ * Keeps detection (which reads and scans other modules) off classes that no binding points at.
+ */
+export declare function collectAgentCandidates(ast: ProgramBody, configuredNames: Iterable<string>): Set<string>;
+//# sourceMappingURL=agentClass.d.ts.map

package/build/types-ts3.8/vite/autoInstrument.d.ts

@@ -1,5 +1,7 @@
-import { ProgramBody } from './transform';
-export declare function sentryCloudflareAutoInstrumentPlugin(): {
+import { ModuleResolver } from './agentClass';
+export declare function sentryCloudflareAutoInstrumentPlugin(options?: {
+    wranglerConfigPath?: string;
+}): {
     name: string;
     configResolved(config: {
         root: string;
@@ -7,15 +9,14 @@ export declare function sentryCloudflareAutoInstrumentPlugin(): {
             warn(msg: string): void;
         };
     }): void;
-    transform(this: {
-        parse(code: string): ProgramBody;
+    transform(this: ModuleResolver & {
         warn?(msg: string): void;
         environment?: {
             name?: string;
         };
-    }, code: string, id: string): {
+    }, code: string, id: string): Promise<{
         code: string;
         map: unknown;
-    } | undefined;
+    } | undefined>;
 };
 //# sourceMappingURL=autoInstrument.d.ts.map

package/build/types-ts3.8/vite/index.d.ts

@@ -2,6 +2,17 @@
  * Options for {@link sentryCloudflareVitePlugin}.
  */
 export interface SentryCloudflareVitePluginOptions {
+    /**
+     * Path to the wrangler config, relative to the Vite root (or absolute).
+     * Set this when your config doesn't use a default name — e.g. when you
+     * pass `configPath: './wrangler.agent.jsonc'` to `@cloudflare/vite-plugin`,
+     * which the Sentry plugin cannot see. When set, only this file is read
+     * (no default-name probing), and a warning is emitted if it is missing or
+     * unparseable.
+     *
+     * @default undefined (probes `wrangler.json`, `wrangler.jsonc`, `wrangler.toml` at the Vite root)
+     */
+    wranglerConfigPath?: string;
     /**
      * Experimental options that may change or be removed without notice.
      */
@@ -74,15 +85,14 @@ export declare function sentryCloudflareVitePlugin(options?: SentryCloudflareVit
             warn(msg: string): void;
         };
     }): void;
-    transform(this: {
-        parse(code: string): import("./transform").ProgramBody;
+    transform(this: import("./agentClass").ModuleResolver & {
         warn?(msg: string): void;
         environment?: {
             name?: string;
         };
-    }, code: string, id: string): {
+    }, code: string, id: string): Promise<{
         code: string;
         map: unknown;
-    } | undefined;
+    } | undefined>;
 } | import("vite").Plugin<any>)[];
 //# sourceMappingURL=index.d.ts.map

package/build/types-ts3.8/vite/moduleShape.d.ts

@@ -0,0 +1,52 @@
+import { ProgramBody } from './transform';
+/** Binding name used for a module's default export. */
+export declare const DEFAULT_EXPORT = "default";
+/** A resolved superclass reference: a bare identifier or a `ns.Member` expression. */
+export type SuperRef = {
+    kind: 'identifier';
+    name: string;
+} | {
+    kind: 'member';
+    object: string;
+    property: string;
+};
+/** The declarations of a single module that binding resolution needs. */
+export interface ModuleShape {
+    /** Top-level class names → their superclass reference (absent when the class has no `extends`). */
+    classes: Map<string, SuperRef | undefined>;
+    /** Local binding name → the import it came from (`imported` is `default` for a default import). */
+    imports: Map<string, {
+        source: string;
+        imported: string;
+    }>;
+    /** Local binding name → module specifier, for `import * as ns from '...'`. */
+    namespaces: Map<string, string>;
+    /** Exported name → the re-export it came from, for `export { x as y } from '...'`. */
+    reexports: Map<string, {
+        source: string;
+        imported: string;
+    }>;
+    /** Exported name → local binding name, for `export { x as y }` without a source. */
+    localExports: Map<string, string>;
+    /** Module specifiers of bare `export * from '...'` declarations. */
+    starExports: string[];
+    /** `export default <Identifier>` — the local name it refers to. */
+    defaultExportName?: string;
+    /** True when the module's default export is a class declaration/expression. */
+    defaultExportIsClass?: boolean;
+    /** Superclass of an anonymous `export default class extends X`. */
+    defaultExportSuper?: SuperRef;
+}
+/** Collect the shape of a module from its parsed AST — used for the already-parsed entry module. */
+export declare function shapeFromAst(ast: ProgramBody): ModuleShape;
+/**
+ * Extract the module shape from **unprocessed source**.
+ *
+ * Sibling modules are read straight from disk (the plugin context's `load()` would deadlock inside a
+ * transform hook), so they may still be TypeScript — which no JS parser will accept. Only
+ * import/export statements and `class X extends Y` headers matter here, and those are
+ * declaration-level syntax a scan can pick out reliably; class bodies, type annotations and generics
+ * are irrelevant and simply skipped.
+ */
+export declare function shapeFromSource(rawCode: string): ModuleShape;
+//# sourceMappingURL=moduleShape.d.ts.map

package/build/types-ts3.8/vite/transform.d.ts

@@ -18,7 +18,7 @@ export interface ProgramBody {
  * config providing only a fallback for self-bound entrypoints whose base class
  * lives in another module.
  */
-export type ClassWrapperKind = 'durableObject' | 'workflow' | 'workerEntrypoint';
+export type ClassWrapperKind = 'durableObject' | 'agent' | 'workflow' | 'workerEntrypoint';
 export interface TransformContext {
     /**
      * Exported class name → the kind of Sentry wrapper to apply. Populated from
@@ -26,6 +26,11 @@ export interface TransformContext {
      * each class's base type.
      */
     classWrappers: Map<string, ClassWrapperKind>;
+    /**
+     * Local class names detected as `agents` Agents. An Agent is configured as a Durable Object in
+     * wrangler, so this upgrades those entries from `durableObject` to `agent`.
+     */
+    agentClasses?: ReadonlySet<string>;
     optionsFn: string;
     /** Import statement prepended when `optionsFn` references a separate module. */
     optionsImport?: string;

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.68.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.68.0",
-    "@sentry/server-utils": "10.68.0",
+    "@sentry/core": "10.70.0",
+    "@sentry/server-utils": "10.70.0",
     "magic-string": "~0.30.21"
   },
   "peerDependencies": {