Sitelet https://github.com/getsentry/sentry-javascript/pull/24993
Skip to content

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

Merged
JPeer264 merged 15 commits into
developfrom
jp/pi-durable-instrumentation
Oct 8, 2026
Merged

JPeer264 merged 15 commits into
developfrom
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 📦

⚠️ Warning: Base artifact is not the latest one, because the latest workflow run is not done yet. This may lead to incorrect results. Try to re-run all tests to get up to date results.

Path Size % Change Change
@sentry/browser 29.8 kB - -
@sentry/browser - with treeshaking flags 27.92 kB - -
@sentry/browser - with treeshaking flags tracing without tracing 27.84 kB - -
@sentry/browser (incl. Tracing) 51.85 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 51.87 kB - -
@sentry/browser (incl. Tracing, Profiling) 54.8 kB - -
@sentry/browser (incl. Tracing, Replay) 91.58 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 80.45 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 96.29 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 109.27 kB - -
@sentry/browser (incl. Feedback) 47.32 kB - -
@sentry/browser (incl. sendFeedback) 34.84 kB - -
@sentry/browser (incl. FeedbackAsync) 39.95 kB - -
@sentry/browser (incl. Metrics) 30.82 kB - -
@sentry/browser (incl. Logs) 31.11 kB - -
@sentry/browser (incl. Metrics & Logs) 31.75 kB - -
@sentry/react 31.63 kB - -
@sentry/react (incl. Tracing) 54.17 kB - -
@sentry/vue 37.84 kB - -
@sentry/vue (incl. Tracing) 54.78 kB - -
@sentry/svelte 29.83 kB - -
@sentry/remix (Remix 3 client bundle) 56.83 kB - -
CDN Bundle 31.53 kB - -
CDN Bundle (incl. Tracing) 52.34 kB - -
CDN Bundle (incl. Logs, Metrics) 33.72 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 54.3 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 74.65 kB - -
CDN Bundle (incl. Tracing, Replay) 90.01 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 91.96 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 96.17 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 98.15 kB - -
CDN Bundle - uncompressed 92.92 kB - -
CDN Bundle (incl. Tracing) - uncompressed 155.46 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 99.46 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 161.41 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 229.5 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 275.63 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 281.57 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 289.33 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 295.26 kB - -
@sentry/nextjs (client) 56.53 kB - -
@sentry/sveltekit (client) 52.23 kB - -
@sentry/core/server 40.86 kB - -
@sentry/core/browser 13.71 kB - -
@sentry/node 149.8 kB +2.69% +3.92 kB 🔺
@sentry/node/import (ESM hook with diagnostics-channel injection) 83.48 kB +0.18% +150 B 🔺
@sentry/node - without tracing 93.88 kB +0.21% +196 B 🔺
@sentry/node - without channel injection 127.97 kB +3.18% +3.94 kB 🔺
@sentry/aws-serverless 102.05 kB +0.15% +147 B 🔺
@sentry/cloudflare (withSentry) - minified 209.71 kB - -
@sentry/cloudflare (withSentry) 519.94 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.

Stale Bugbot comment from a previous run.

Comment thread packages/server-utils/src/ai/pi-durable/index.ts
Comment thread packages/server-utils/src/integrations/index.ts
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from 4fc5960 to f8eb62c Compare October 5, 2026 09:44
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from f8eb62c to c8a1208 Compare October 5, 2026 11: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.

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Fix All in Cursor

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit c8a1208. Configure here.

@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from c8a1208 to 189004f Compare October 5, 2026 12:53
@JPeer264
JPeer264 marked this pull request as ready for review October 5, 2026 13:24
@JPeer264
JPeer264 requested review from a team as code owners October 5, 2026 13:24
@JPeer264
JPeer264 requested review from chargome and s1gr1d and removed request for a team October 5, 2026 13:24
Comment thread packages/server-utils/src/ai/pi-durable/runs.ts
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from 1cccf5e to c42eafb Compare October 7, 2026 17:03
Comment thread packages/server-utils/src/ai/pi-durable/index.ts
@JPeer264
JPeer264 requested a review from andreiborza October 8, 2026 05:58
Comment thread packages/server-utils/src/utils/withCleanScopes.ts
JPeer264 and others added 15 commits October 8, 2026 13:27
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>
Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com>
@JPeer264
JPeer264 force-pushed the jp/pi-durable-instrumentation branch from dcb4c47 to 31179ae Compare October 8, 2026 11:27
Comment thread packages/server-utils/src/ai/pi-durable/runs.ts
@JPeer264
JPeer264 merged commit 04f7cb9 into develop Oct 8, 2026
529 of 530 checks passed
@JPeer264
JPeer264 deleted the jp/pi-durable-instrumentation branch October 8, 2026 12:49
JPeer264 added a commit that referenced this pull request Oct 8, 2026
Cloudflare now hosts pi-durable in Durable Objects through the Agents
SDK `PiHarness`
([changelog](https://developers.cloudflare.com/changelog/post/2026-10-02-pi-harness/)).
This app runs pi-durable that way, with `@sentry/cloudflare/vite` as the
only Sentry setup. It checks that a prompt becomes an `invoke_agent`
trace with `chat`, `execute_tool` and provider `http.client` spans, that
a throwing tool is reported on its span, and that a run resumes in a new
trace after the Durable Object resets during a tool call. The reset uses
`ctx.abort()`, which drops the object like an eviction; the next request
starts it again, and `PiHarness` resumes pi from its SQLite state.

Like `node-pi-durable` and `cloudflare-think`, it calls a real model
through OpenRouter, so it is optional. The changelog example uses
Workers AI (`createAI({ binding: env.AI })`), but the AI binding needs a
Cloudflare account even in local dev, so that path has a unit test in
#24993 instead.

This app found a bug that #24993 now fixes: `@sentry/cloudflare`
initializes the SDK inside each request, so the client is on the scope
of that request only. The task phases ran on a copy of the default
scope, had no client, and dropped every pi-durable span and error.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
andreiborza added a commit to getsentry/sentry-docs that referenced this pull request Oct 9, 2026
<!-- Keep the urgency section so automation can prioritize this PR. You
may delete other sections you don't need. -->

## DESCRIBE YOUR PR

Adds a dedicated `javascript.pi-durable` platform guide for the Pi
Durable integration added in getsentry/sentry-javascript#24993 (see also
the [Pi Durable announcement](https://earendil.com/posts/pi-durable/)).
It follows the same structure as the Flue, Eve, and Mastra guides.

- `docs/platforms/javascript/guides/pi-durable/index.mdx`: Node.js setup
(preload `instrument.mjs` with `--import`, or use the bundler plugin)
- `docs/platforms/javascript/guides/pi-durable/cloudflare.mdx`:
Cloudflare setup (`sentryCloudflareVitePlugin()` +
`instrument.server.ts`, with an Agents SDK `PiHarness` example)
- `includes/pi-durable/`: shared sections covering experimental status,
captured telemetry (`gen_ai.invoke_agent` / `gen_ai.chat` /
`gen_ai.execute_tool`), conversation IDs across restarts, crash
recovery, captured errors, which provider integrations get skipped,
current gaps, verification, and next steps
- Adds `javascript.pi-durable` to common-page platform lists wherever
Mastra appears (install-method pages stay visible, since a Pi Durable
app controls its own startup)
- Adds a Pi icon (`src/icons/pi-durable.svg`), plus entries on the Agent
Tracing index and the Agents getting-started page

Bun and Deno are left out for now because their setup couldn't be
verified. Only Node and Cloudflare are documented.

## IS YOUR CHANGE URGENT?

- [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD
- [ ] Other deadline: YYYY-MM-DD
- [x] No deadline: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
supplied a deadline.

## PRE-MERGE CHECKLIST

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

<!-- junior-request-attribution:start -->
via **Andrei Borza**.
<!-- junior-request-attribution:end -->

<!-- junior-session-footer:start -->
<!-- junior-conversation-id:slack%3AC0BKK9QLCUA%3A1791533598.406349 -->

--

[View Junior
Session](https://junior-prod.sentry.dev/conversations/slack%3AC0BKK9QLCUA%3A1791533598.406349)
[[Sentry]](https://sentry.sentry.io/explore/conversations/slack%3AC0BKK9QLCUA%3A1791533598.406349/?project=4510944073809921)

<!-- junior-session-footer:end -->

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Andrei Borza <andrei.borza@sentry.io>
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.

2 participants