feat: Cloudflare-native AI tracing (agents/observability/ai)

.changeset/agent-initialization-span.md

@@ -0,0 +1,7 @@
+---
+"agents": minor
+"@cloudflare/ai-chat": patch
+"@cloudflare/think": patch
+---
+
+Group SDK-managed initialization, startup, chat interactions, turns, and durable submissions into semantic phases. Storage-heavy setup, hydration, recovery, request persistence, and response persistence each receive a named bucket, keeping inference and tool spans visible without discarding lower-level Durable Object SQLite spans. Each span records agent identity, storage phase, a stable marker for UI grouping, and operation-specific metadata. No-op on runtimes without the `tracing` API.

.changeset/agents-observability-ai-tracing.md

@@ -0,0 +1,5 @@
+---
+"agents": minor
+---
+
+Add `agents/observability/ai` with `wrapAISDK` for AI SDK v6 and `createAISDKTelemetry` for AI SDK v7. Both project Cloudflare-native `invoke_agent {agent}`, `chat {model}`, and `execute_tool {tool}` spans using scalar OpenTelemetry GenAI attributes, including request settings, token usage, finish reasons, tool-call IDs, model-call time to first chunk, bounded AI SDK v6 approval lifecycle spans, and conditional AI Gateway log references. Payload storage is opt-in: `storeMessages` writes OTel-schema input/output message arrays to `chat` (`{ role, parts }`, canonical text/reasoning/tool parts, and output `finish_reason`; oldest messages are dropped past the budget while protecting the first two), and `storeTools` writes arguments/results to `execute_tool`. The flags themselves are never emitted as span attributes. Schemas, request headers, provider options, and raw errors remain excluded.

.changeset/think-alarm-owned-submissions.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/think": patch
+---
+
+Run durable submissions only from their awaited scheduled drain, preventing model work and tracing spans from outliving the short submission-acceptance invocation.

.changeset/think-out-of-box-tracing.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/think": minor
+---
+
+Think agents emit Cloudflare-native traces out of the box with no tracing setup beyond enabling Worker traces. Named lifecycle and storage-phase spans group Durable Object internals around startup, request persistence, turn preparation, inference, result persistence, recovery, alarms, and durable submissions. Every inference call produces an `invoke_agent {agent class}` span with `chat {model}` and `execute_tool {tool}` children. Think supplies durable identity and turn metadata. Payload storage remains off by default; agents can set `storeMessages` for OTel-schema model messages (`{ role, parts }`, canonical tool parts, and output `finish_reason`) on `chat` and `storeTools` for tool arguments/results on `execute_tool`. These flags configure the wrapper and are never emitted as metadata or attributes. Model streams are finalized on early exit, and durable submissions run from their awaited alarm invocation so spans do not outlive invocation boundaries.

design/think-durable-submissions.md

@@ -160,10 +160,13 @@ avoid unsafe replay:
 
 1. `submitMessages()` serializes and sanitizes the messages, inserts a
    `pending` row, emits `submission:create`, emits the initial `pending` status,
-   schedules an idempotent `_drainThinkSubmissions` alarm, and starts an
-   in-memory drain.
-2. `_drainSubmissions()` claims the oldest `pending` row by conditionally
-   updating it to `running`.
+   and schedules an idempotent `_drainThinkSubmissions` alarm. It does not start
+   model work inside the short acceptance invocation.
+2. The awaited `_drainThinkSubmissions` alarm owns `_drainSubmissions()`, which
+   claims the oldest `pending` row by conditionally updating it to `running`.
+   Keeping execution inside that alarm invocation also gives tracing spans the
+   correct lifecycle owner; no `invoke_agent` span crosses an invocation
+   boundary.
 3. `_runSubmission()` calls the same programmatic turn path used by
    `saveMessages()`, with the submission id as the request id.
 4. `_runProgrammaticMessagesTurn()` appends submitted messages to Session,

packages/agents/package.json

@@ -140,6 +140,11 @@
       "import": "./dist/observability/index.js",
       "require": "./dist/observability/index.js"
     },
+    "./observability/ai": {
+      "types": "./dist/observability/ai/index.d.ts",
+      "import": "./dist/observability/ai/index.js",
+      "require": "./dist/observability/ai/index.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js",

packages/agents/scripts/build.ts

@@ -18,6 +18,7 @@ const entries = [
   "src/mcp/do-oauth-client-provider.ts",
   "src/mcp/x402.ts",
   "src/observability/index.ts",
+  "src/observability/ai/index.ts",
   "src/codemode/ai.ts",
   "src/experimental/memory/session/index.ts",
   "src/experimental/memory/utils/index.ts",