Skip to content

feat(server-utils): Add instrumentation for pi-durable - #24993

Draft
JPeer264 wants to merge 1 commit into
jp/bun-conversation-id-integrationfrom
jp/pi-durable-instrumentation
Draft

JPeer264 wants to merge 1 commit into
jp/bun-conversation-id-integrationfrom
jp/pi-durable-instrumentation

Conversation

@JPeer264

@JPeer264 JPeer264 commented Oct 2, 2026 •

Copy link
Copy Markdown
Member

Adds piDurableIntegration for @earendil-works/pi-durable, Earendil's new durable agent harness. It is on by default in Node, Bun and Deno, and in a Worker built with @sentry/cloudflare/vite, which covers pi-durable in a Durable Object through the Agents SDK PiHarness. Each run becomes its own invoke_agent trace with chat and execute_tool children, and the first run of a subagent conversation nests under the tool call that created it.

pi-durable has no telemetry hooks (pi-telemetry exists, but no pi package emits spans through it yet), so the integration hooks Harness.open() and wraps the models and registry it receives. The wrapped options keep the caller's options as prototype, because pi-durable reads settings, env and conversationCreated at every use.

Decisions worth a look:

  • Runs are tracked per conversation. pi-durable hands run control to a new pi.generation task after every tool round, so no single task spans a run. The run span ends when the commit that removes pi.live.run goes through, or when the Harness closes with the run in flight.
  • Each run starts a new trace in clean scopes. The scheduler runs task phases in whatever async context last woke it, often an unrelated request. Forking that context attached runs to the wrong request and the wrong conversation. Only the client of that context is kept, because @sentry/cloudflare binds the client to the scope of each request, not to the default scope.
  • gen_ai.conversation.id is <harness id>:<conversation id>. pi-durable numbers conversations per storage from 1, so the bare id would merge every root conversation into one. The cost is a new id after a restart (on Cloudflare, after every restart of the Durable Object), until pi-durable has a stable storage id.
  • Tool spans record the result the model receives, read from the committed result entry. That covers output streamed through api.output() (all of bash) and results an afterTool hook redacted.
  • Errors: failures pi-durable only passes to onReport (throwing hooks or sections) and task phases that throw are captured. Throws of the built-in coding tools are not, because bash throws for every non-zero exit, a normal result for a coding agent. The built-in tools are recognized by their factories (createBashTool() and friends), so an app that registers them in an extension of its own gets the same treatment. The span keeps its error status.
  • The provider SDK integrations are skipped process-wide from the first run on, as the Flue and LangChain integrations do: pi-ai sends its requests through the openai, @anthropic-ai/sdk and @google/genai clients, or through the Workers AI binding with createAI() of agents/models/pi-ai, and those integrations cannot tell pi-ai's calls from the app's own. Bedrock requests go through the AWS SDK, which awsIntegration still reports twice; that skip is a follow-up.

Messages, token usage and finish reasons go through the pi-ai mapper from the Flue fix, and the system prompt and tools are replayed from pi-durable's positional system messages.

Not covered yet: spans for tool calls pi-durable answers without running execute(), spans for custom tasks, agent names (pi-durable has none), a link between a run and the request that submitted it, a marker for compaction requests, and an error event for a failed model request (the chat span carries the status).

🤖 Generated with Claude Code

@JPeer264
JPeer264 added this pull request to stack #25002 October 2, 2026 13:14
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

size-limit report 📦

Path Size % Change Change
@sentry/browser 29.52 kB - -
@sentry/browser - with treeshaking flags 27.68 kB - -
@sentry/browser - with treeshaking flags tracing without tracing 27.57 kB - -
@sentry/browser (incl. Tracing) 51.42 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 51.44 kB - -
@sentry/browser (incl. Tracing, Profiling) 54.44 kB - -
@sentry/browser (incl. Tracing, Replay) 91.03 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 80.03 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 95.73 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 108.68 kB - -
@sentry/browser (incl. Feedback) 47.02 kB - -
@sentry/browser (incl. sendFeedback) 34.58 kB - -
@sentry/browser (incl. FeedbackAsync) 39.68 kB - -
@sentry/browser (incl. Metrics) 30.53 kB - -
@sentry/browser (incl. Logs) 30.82 kB - -
@sentry/browser (incl. Metrics & Logs) 31.47 kB - -
@sentry/react 31.36 kB - -
@sentry/react (incl. Tracing) 53.78 kB - -
@sentry/vue 37.49 kB - -
@sentry/vue (incl. Tracing) 54.34 kB - -
@sentry/svelte 29.55 kB - -
@sentry/remix (Remix 3 client bundle) 55.78 kB - -
CDN Bundle 31.22 kB - -
CDN Bundle (incl. Tracing) 51.98 kB - -
CDN Bundle (incl. Logs, Metrics) 33.46 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 53.92 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 74.21 kB - -
CDN Bundle (incl. Tracing, Replay) 89.54 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 91.51 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 95.72 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 97.71 kB - -
CDN Bundle - uncompressed 92.14 kB - -
CDN Bundle (incl. Tracing) - uncompressed 154.49 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 98.71 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 160.44 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 228.28 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 274.22 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 280.16 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 287.92 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 293.85 kB - -
@sentry/nextjs (client) 56.31 kB - -
@sentry/sveltekit (client) 51.85 kB - -
@sentry/core/server 40.58 kB - -
@sentry/core/browser 13.63 kB - -
@sentry/node 148.54 kB +2.63% +3.8 kB 🔺
@sentry/node/import (ESM hook with diagnostics-channel injection) 83.37 kB +0.18% +149 B 🔺
@sentry/node - without tracing 93.47 kB +0.19% +173 B 🔺
@sentry/node - without channel injection 126.7 kB +3.06% +3.75 kB 🔺
@sentry/aws-serverless 101.73 kB +0.15% +151 B 🔺
@sentry/cloudflare (withSentry) - minified 208.62 kB - -
@sentry/cloudflare (withSentry) 517.25 kB - -

View base workflow run

@JPeer264
JPeer264 removed this pull request from stack #25002 October 2, 2026 13:31
@JPeer264
JPeer264 changed the base branch from jp/flue-map-messages-conventions to jp/bun-conversation-id-integration October 2, 2026 13:39
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from 1dad424 to 91a0b35 Compare October 2, 2026 13:39
@JPeer264
JPeer264 added this pull request to stack #25004 October 2, 2026 13:57
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from 91a0b35 to 26d39c9 Compare October 2, 2026 16:59
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from 26d39c9 to 4fc5960 Compare October 3, 2026 16:23
@JPeer264
JPeer264 removed this pull request from stack #25004 October 5, 2026 07:21
@JPeer264
JPeer264 added this pull request to stack #25029 October 5, 2026 07:22
@JPeer264

JPeer264 commented Oct 5, 2026

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 4fc5960. Configure here.

const run =
isRunWork || kind === PI_TASK.COMPACTION
? (runs.active.get(conversationId) ?? (isRunWork ? startRun(conversationId, runs) : undefined))
: undefined;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Abort can start leaked agent runs

Medium Severity

abort is wrapped with the same runPhase path as live generation and tool work, and that path starts a new invoke_agent run whenever the conversation has no active run. subscribeClose already ends those runs when close() begins, after which built-in abort handlers still run. A late abort then opens a fresh run that close will not see, so the span can leak until the tracker overflows.

Additional Locations (2)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 4fc5960. Configure here.

langChainIntegration(),
langGraphIntegration(),
mastraIntegration(),
piDurableIntegration(),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Default enablement lacks changelog notes

Low Severity

piDurableIntegration is added to default tracing integrations, and the first model request disables the OpenAI, Anthropic, Google GenAI, and Workers AI integrations process-wide. That is a silent default change for apps that already use pi-durable alongside those SDKs, and Unreleased has no changelog or migration note. Flagged because the review rules call out silent default changes without migration notes.

Additional Locations (1)
Fix in Cursor Fix in Web

Triggered by project rule: PR Review Guidelines for Cursor Bot

Reviewed by Cursor Bugbot for commit 4fc5960. Configure here.

pi-durable has no telemetry hooks, so `piDurableIntegration` wraps the
`models` and `registry` passed to `Harness.open()`. Each run becomes its
own `invoke_agent` trace with `chat` and `execute_tool` children, and a
subagent run nests under the tool call that started it.

Messages are mapped to the gen_ai conventions, and the system prompt and
tools are read from pi-durable's positional system messages. Tool spans
record the result the model receives. Failures pi-durable only reports,
and task phases that throw, are captured. Throws of the built-in coding
tools are not, because they report expected results to the model.

On Cloudflare it also covers pi-durable in a Durable Object through the
Agents SDK `PiHarness`, including requests that pi-ai sends through the
Workers AI binding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from 4fc5960 to f8eb62c Compare October 5, 2026 09:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant