@narumitw/pi-otel 0.0.0-stage → 0.54.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/CHANGELOG.md +162 -0
  2. package/LICENSE +21 -0
  3. package/README.md +368 -2
  4. package/dist/chunks/chunk-DSQBXICE.ts +150 -0
  5. package/dist/chunks/chunk-DSQBXICE.ts.map +7 -0
  6. package/dist/chunks/runtime-X3YFJUNH.ts +404 -0
  7. package/dist/chunks/runtime-X3YFJUNH.ts.map +7 -0
  8. package/dist/config.d.ts +36 -0
  9. package/dist/durable-projection.d.ts +9 -0
  10. package/dist/durable-recorder.d.ts +57 -0
  11. package/dist/durable-state.d.ts +43 -0
  12. package/dist/durable.d.ts +25 -0
  13. package/dist/durable.js +897 -0
  14. package/dist/durable.js.map +7 -0
  15. package/dist/git.d.ts +5 -0
  16. package/dist/index.d.ts +2 -0
  17. package/dist/index.js +1732 -0
  18. package/dist/index.js.map +7 -0
  19. package/dist/index.ts +1874 -0
  20. package/dist/index.ts.map +7 -0
  21. package/dist/library-chunks/chunk-7DN64UHE.js +158 -0
  22. package/dist/library-chunks/chunk-7DN64UHE.js.map +7 -0
  23. package/dist/library-chunks/chunk-7JGM5RS3.js +72 -0
  24. package/dist/library-chunks/chunk-7JGM5RS3.js.map +7 -0
  25. package/dist/library-chunks/chunk-BBL32ZV5.js +84 -0
  26. package/dist/library-chunks/chunk-BBL32ZV5.js.map +7 -0
  27. package/dist/library-chunks/runtime-554E6FVF.js +406 -0
  28. package/dist/library-chunks/runtime-554E6FVF.js.map +7 -0
  29. package/dist/otel.d.ts +13 -0
  30. package/dist/otlp-settings.d.ts +8 -0
  31. package/dist/pi-session.d.ts +43 -0
  32. package/dist/public-api.d.ts +2 -0
  33. package/dist/runtime-api.d.ts +6 -0
  34. package/dist/runtime-core.d.ts +26 -0
  35. package/dist/runtime-defaults.d.ts +1 -0
  36. package/dist/runtime.d.ts +26 -0
  37. package/dist/sanitizer.d.ts +2 -0
  38. package/dist/tracing.d.ts +198 -0
  39. package/docs/durable.md +128 -0
  40. package/package.json +87 -4
  41. package/src/config.ts +330 -0
  42. package/src/durable-projection.ts +112 -0
  43. package/src/durable-recorder.ts +539 -0
  44. package/src/durable-state.ts +135 -0
  45. package/src/durable.ts +364 -0
  46. package/src/git.ts +64 -0
  47. package/src/index.ts +12 -0
  48. package/src/otel.ts +397 -0
  49. package/src/otlp-settings.ts +72 -0
  50. package/src/pi-session.ts +570 -0
  51. package/src/public-api.ts +13 -0
  52. package/src/runtime-api.ts +16 -0
  53. package/src/runtime-core.ts +114 -0
  54. package/src/runtime-defaults.ts +1 -0
  55. package/src/runtime.ts +509 -0
  56. package/src/sanitizer.ts +157 -0
  57. package/src/tracing.ts +940 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,162 @@
1
+ # @narumitw/pi-otel
2
+
3
+ Versions through 0.54.3 were released as `@narumitw/pi-langfuse`.
4
+
5
+ ## 0.54.3
6
+
7
+ ### Patch Changes
8
+
9
+ - ed7ea5a: Replace the Langfuse JavaScript SDK with OpenTelemetry's official tracing and OTLP HTTP packages. Keep the existing Pi settings and Langfuse trace schema.
10
+ - 25eef0a: Update the runtime libraries for AgentFS shell execution, Langfuse trace export, Starship pattern matching, subagent ignore rules, and sync daemon XML parsing and glob matching.
11
+
12
+ ## 0.54.2
13
+
14
+ ### Patch Changes
15
+
16
+ - Updated dependencies [cf7b63d]
17
+ - @narumitw/pi-tui-kit@0.70.0
18
+
19
+ ## 0.54.1
20
+
21
+ ### Patch Changes
22
+
23
+ - 45401e4: Update runtime dependencies within supported peer dependency ranges.
24
+
25
+ ## 0.54.0
26
+
27
+ ### Minor Changes
28
+
29
+ - 5120d4d: Support Pi durable and Chord 1.5 through their public synchronous observers. Replace the removed event stream with ordered, bounded committed delivery, retain final tool arguments and submission correlation, and join observation cancellation and shutdown without controlling execution. Preserve committed-only privacy filtering, snapshot recovery, and continue/afterRun boundaries. Raise the experimental durable and Chord peer floors to the supported runtime contract.
30
+
31
+ ### Patch Changes
32
+
33
+ - 0339567: Bound Git metadata queries and omit incomplete branch or commit output from traces.
34
+ - 811b195: Retain provider-confirmed zero totals in live generation costs and compaction metadata without replacing them with estimated component sums. Export cost provenance as metadata and preserve the unknown-zero fallback.
35
+ - e484010: Include the existing package-root CHANGELOG.md in extension tarballs so Pi can show native update notices. Keep Changesets version headings and Pi's first-observation and collapseChangelog behavior unchanged.
36
+ - bed3e2b: Preserve boolean cost-total provenance in durable assistant and nested-tool trace metadata without changing numeric costs or zero-cost rules.
37
+ - Updated dependencies [54f2700]
38
+ - Updated dependencies [6c76ef1]
39
+ - @narumitw/pi-tui-kit@0.69.0
40
+
41
+ ## 0.53.3
42
+
43
+ ### Patch Changes
44
+
45
+ - fa69a68: Keep OpenTelemetry dependencies compatible with the tracing SDK by bounding the API below 1.10 and declaring the matching OTLP exporter base directly. This prevents runtime import failures from the incompatible exporter release line.
46
+
47
+ ## 0.53.2
48
+
49
+ ### Patch Changes
50
+
51
+ - 4a266d6: Update the Turso database dependency to 0.8.3 and the Langfuse runtime dependencies to 6.0.1.
52
+
53
+ ## 0.53.1
54
+
55
+ ### Patch Changes
56
+
57
+ - 1f1c293: Update React to 19.3.1, Langfuse to 6.0, and the TypeSafe SDK to 0.7 in their respective packages. Preserve trace-only input and output updates, metadata encoding, and root observation detection with Langfuse 6. Accept unreported TypeSafe token usage without rejecting valid answers.
58
+ - Updated dependencies [077137a]
59
+ - Updated dependencies [9f80b89]
60
+ - Updated dependencies [efc474c]
61
+ - @narumitw/pi-tui-kit@0.66.0
62
+
63
+ ## 0.53.0
64
+
65
+ ### Minor Changes
66
+
67
+ - 1dabb0b: Upgrade the experimental durable adapter contract to pi-durable 1.2.0 and Chord ^1.2.0. Update durable tool test results to the public `output` field and keep compatibility guidance aligned with the tested host versions.
68
+
69
+ ### Patch Changes
70
+
71
+ - fe6e621: Support Pi's user and custom `before_agent_start` events, capturing custom message content with existing trace sanitization.
72
+
73
+ ## 0.52.0
74
+
75
+ ### Minor Changes
76
+
77
+ - 9fe3ecc: Add an experimental public `/durable` integration for pi-durable 1.0.4, reusing the existing Langfuse runtime and tracing core without loading coding-agent registration. Trace committed submission outcomes, generation content and usage, and tool activity with isolated host correlation, fail-open observer cleanup and explicit snapshot/resynchronization semantics. Preserve existing coding-agent exports and behavior, and make shared-runtime shutdown idempotent under reentrant host callbacks.
78
+
79
+ ## 0.51.2
80
+
81
+ ### Patch Changes
82
+
83
+ - 2246daa: Update runtime dependencies for D-Bus, peer networking, and tracing.
84
+
85
+ ## 0.51.1
86
+
87
+ ### Patch Changes
88
+
89
+ - 8abd5b7: Keep generated extension runtime graphs inside Pi's Jiti-loaded TypeScript path to avoid duplicate peer-runtime evaluation during startup. Add measured generated runtimes for Context Management, Herdr, and TypeSafe Search.
90
+
91
+ ## 0.51.0
92
+
93
+ ### Minor Changes
94
+
95
+ - 2e1031d: Add public process-level Langfuse runtime and per-session Pi tracing controller APIs for safely tracing multiple concurrent sessions in one host process.
96
+
97
+ ### Patch Changes
98
+
99
+ - 67a3049: Adapt provider, transcript, usage, deferred-tool, and telemetry behavior to Pi's current runtime contracts, including accurate cache-warming accounting and exclusion from ordinary generation traces.
100
+
101
+ ## 0.50.6
102
+
103
+ ### Patch Changes
104
+
105
+ - d365daa: Publish the updated Langfuse tracing and OpenTelemetry runtime dependency ranges.
106
+ - Updated dependencies [d365daa]
107
+ - @narumitw/pi-tui-kit@0.63.1
108
+
109
+ ## 0.50.5
110
+
111
+ ### Patch Changes
112
+
113
+ - Updated dependencies [40182e5]
114
+ - @narumitw/pi-tui-kit@0.59.0
115
+
116
+ ## 0.50.4
117
+
118
+ ### Patch Changes
119
+
120
+ - 3346683: Publish generated lazy chunks at the JavaScript paths referenced by each extension runtime so deferred menus and implementations load correctly through Pi's Jiti loader.
121
+ - Updated dependencies [b9eba3a]
122
+ - @narumitw/pi-tui-kit@0.58.0
123
+
124
+ ## 0.50.3
125
+
126
+ ### Patch Changes
127
+
128
+ - Updated dependencies [6574232]
129
+ - Updated dependencies [cddc265]
130
+ - @narumitw/pi-tui-kit@0.57.0
131
+
132
+ ## 0.50.2
133
+
134
+ ### Patch Changes
135
+
136
+ - dc4f90e: Load each extension from a generated source-mapped Jiti runtime while preserving first-use feature boundaries.
137
+
138
+ ## 0.50.1
139
+
140
+ ### Patch Changes
141
+
142
+ - Updated dependencies [8bead31]
143
+ - @narumitw/pi-tui-kit@0.56.0
144
+
145
+ ## 0.50.0
146
+
147
+ ### Minor Changes
148
+
149
+ - 1086433: Add an optional `userId` setting to `pi-langfuse.json` and stamp it on every observation so Langfuse attributes traces and sessions to a user.
150
+
151
+ ### Patch Changes
152
+
153
+ - Updated dependencies [3176172]
154
+ - @narumitw/pi-tui-kit@0.55.0
155
+
156
+ ## 0.49.4
157
+
158
+ ### Patch Changes
159
+
160
+ - 1e630c1: Stamp the Langfuse session ID on every observation and apply session updates so session-level token and cost totals include generations.
161
+ - Updated dependencies [11bdf1e]
162
+ - @narumitw/pi-tui-kit@0.54.1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 narumiruna
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,369 @@
1
- # Temporary Holding Version
1
+ # 🪢 pi-otel — Export Pi Traces with OpenTelemetry
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@narumitw/pi-otel)](https://www.npmjs.com/package/@narumitw/pi-otel) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
+
5
+ Export Pi coding-agent and durable conversation traces to an OpenTelemetry collector or [Langfuse](https://langfuse.com/).
6
+
7
+ ## ✨ Features
8
+
9
+ - Exports to a custom OTLP/HTTP endpoint or directly to Langfuse with its existing trace format.
10
+ - Groups each settled agent run into one trace with indexed attempt spans for retries and queued continuations.
11
+ - Records bounded provider requests, final assistant output, model identity, time to first content, usage, known costs, and safe response diagnostics.
12
+ - Captures final tool inputs and outputs, progress timing, duration, failures, and structural compaction events.
13
+ - Adds session, context, Git branch, commit, and aggregate counters as searchable metadata.
14
+ - Supports metadata-only tracing when content capture is disabled.
15
+ - Keeps the default extension's credentials in a private local settings file and redacts them from exported data.
16
+ - Supports multiple concurrent Pi sessions through one process-owned runtime without sharing session trace state.
17
+ - Provides an opt-in public `/durable` adapter for committed submissions, model generations and tool activity without `AgentSession`.
18
+ - Batches exports without delaying normal completion and isolates its OpenTelemetry provider from other extensions.
19
+
20
+ ## 📦 Install
21
+
22
+ Until the first npm release, use the local checkout instructions below. Once published, install with:
23
+
24
+ ```bash
25
+ pi install npm:@narumitw/pi-otel
26
+ ```
27
+
28
+ Try the published package without installing it:
29
+
30
+ ```bash
31
+ pi -e npm:@narumitw/pi-otel
32
+ ```
33
+
34
+ Build and load a local checkout from the repository root:
35
+
36
+ ```bash
37
+ npm --workspace @narumitw/pi-otel run build
38
+ pi -e ./packages/pi-otel
39
+ ```
40
+
41
+ The package declares `dist/index.ts`, so Pi cannot load an unbuilt local checkout.
42
+ Supported Pi runtimes require Node.js >=22.19.0.
43
+ The durable adapter targets experimental Pi durable APIs within the peer ranges in [`package.json`](./package.json); review its [compatibility and upgrade checks](./docs/durable.md#compatibility) before enabling or upgrading it.
44
+ Pi extensions run with your user permissions. Review the [data-export behavior](#-security-and-privacy) before enabling tracing.
45
+
46
+ If you already use `pi-langfuse`, uninstall it before loading `pi-otel` to avoid duplicate tracing and slash commands.
47
+ Existing Langfuse settings still work; see [Settings](#-settings). Host applications can change their import paths to `@narumitw/pi-otel` or `@narumitw/pi-otel/durable` without renaming their Langfuse factories.
48
+
49
+ ## 🚀 Quick start
50
+
51
+ Start an OpenTelemetry Collector with the OTLP HTTP receiver enabled. Save this as `~/.pi/agent/pi-otel.json`:
52
+
53
+ ```json
54
+ {
55
+ "backend": "otlp",
56
+ "endpoint": "http://localhost:4318/v1/traces"
57
+ }
58
+ ```
59
+
60
+ Restart Pi, run a prompt, then use `/otel` → **Flush completed traces for this session** to send completed traces to the collector. Model and tool metadata are exported; prompts, replies, and tool contents stay local by default.
61
+
62
+ For Langfuse instead, use `/otel` → **Set up Langfuse for this Pi agent directory** and restart Pi, or keep your existing `pi-langfuse.json`.
63
+
64
+ ## 🧩 Host application embedding
65
+
66
+ A host that manages multiple Pi sessions can share one process-level runtime and create one tracing controller for each session:
67
+
68
+ ```ts
69
+ import { DefaultResourceLoader, createAgentSession } from "@earendil-works/pi-coding-agent";
70
+ import {
71
+ createLangfuseRuntime,
72
+ createPiLangfuseSession,
73
+ } from "@narumitw/pi-otel";
74
+
75
+ const runtime = await createLangfuseRuntime({
76
+ config: { environment: "production" },
77
+ // publicKey, secretKey, baseUrl, and release may come from standard Langfuse env vars.
78
+ });
79
+
80
+ const tracing = createPiLangfuseSession(runtime, {
81
+ traceName: "support-agent",
82
+ sessionId: hostSessionId,
83
+ userId: accountId,
84
+ tags: ["support"],
85
+ metadata: { tenant: tenantId },
86
+ captureContent: false,
87
+ onTraceId: (traceId) => correlateTrace(hostSessionId, traceId),
88
+ });
89
+
90
+ const resourceLoader = new DefaultResourceLoader({
91
+ ...hostResourceOptions,
92
+ noExtensions: true, // Keep auto-discovered extensions out of this controlled host session.
93
+ extensionFactories: [{ name: "langfuse", factory: tracing.extension }],
94
+ });
95
+ await resourceLoader.reload();
96
+ const { session } = await createAgentSession({
97
+ ...hostSessionOptions,
98
+ resourceLoader,
99
+ });
100
+ await session.bindExtensions({});
101
+
102
+ tracing.setRequestId(incomingRequestId); // Applies to the next root trace only.
103
+ await session.prompt(userPrompt);
104
+
105
+ // When this session ends:
106
+ await tracing.dispose();
107
+ session.dispose();
108
+
109
+ // Once, after every hosted session has been disposed:
110
+ await runtime.shutdown();
111
+ ```
112
+
113
+ Create the runtime once per process, create a separate controller per Pi `AgentSession`, and explicitly dispose the controller because `AgentSession.dispose()` does not emit Pi's `session_shutdown` event.
114
+ The controller's extension factory may be reused when that session's resource loader reloads, but it must not be attached to another active `AgentSession`.
115
+ Controller disposal ends only that session's open observations; it never flushes or shuts down the shared exporter.
116
+ `runtime.shutdown()` rejects new work, disposes any remaining controllers, flushes, and shuts down the provider once.
117
+ Both operations are idempotent.
118
+
119
+ Do not also auto-load this package's default extension into a session that uses `tracing.extension`, or that session will be traced twice.
120
+ Each process supports one active export connection. A conflicting connection requires a restart instead of replacing the active provider.
121
+
122
+ For a generic OTLP receiver, import `createOtelRuntime` from the same package (or from `/durable` for a durable host) and call it with `{ endpoint, headers, serviceName }`.
123
+ Pass that runtime to the same session or durable observer factory. Only `endpoint` is required; use explicit options, not environment variables, to configure the OTLP connection.
124
+ Set `captureContent: false` on embedded observers for metadata-only tracing; the default extension's JSON settings do not configure those observers.
125
+
126
+ `createLangfuseRuntime()` resolves fields in this order: `config`, the supplied `env` object (or `process.env`), then defaults.
127
+ It supports `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`, `LANGFUSE_TRACING_ENVIRONMENT`, and `LANGFUSE_RELEASE`.
128
+ Pass `env: false` to disable these lookups. The default extension resolves these fields only from its settings file.
129
+
130
+ `setRequestId()` snapshots `pi.request.id` when the next root trace starts; changing or clearing it never rewrites an active trace.
131
+ `traceName` changes the trace-name attribute without changing span names or hierarchy.
132
+ `onTraceId` runs once after each root is created, including automatic-continuation roots, and callback errors are intentionally ignored so host code cannot corrupt tracing cleanup.
133
+ Custom metadata is sanitized, bounded, and exported even when `captureContent` is `false`; package-owned `pi.*` fields cannot be overridden.
134
+ Treat custom metadata, tags, session IDs, user IDs, request IDs, and trace names as exported data.
135
+
136
+ ## 🧱 Durable host applications
137
+
138
+ **Experimental:** use the dedicated public export with Pi durable and Chord versions that satisfy the package's declared peer ranges, plus compatible Pi AI.
139
+ Install those host dependencies explicitly; the durable entry does not require or load coding-agent registration.
140
+
141
+ ```ts
142
+ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
143
+ import {
144
+ createLangfuseRuntime,
145
+ createPiLangfuseDurableConversation,
146
+ } from "@narumitw/pi-otel/durable";
147
+
148
+ const runtime = await createLangfuseRuntime(); // Standard Langfuse credentials/environment.
149
+ const tracing = await createPiLangfuseDurableConversation(runtime, {
150
+ harness, // Existing, authorized host-owned Harness.
151
+ conversationId: conversation.id,
152
+ context: BACKGROUND_CONTEXT,
153
+ sessionId: hostConversationId,
154
+ userId: accountId,
155
+ applicationId: "support-service",
156
+ captureContent: false,
157
+ });
158
+ const submission = await conversation.submit({
159
+ type: "input", content: userPrompt, requestId: incomingRequestId,
160
+ }, executionContext);
161
+ const result = await submission.wait(executionContext); // Host execution responsibility.
162
+ await tracing.observeSubmission(submission.id); // Optional committed-status reconciliation.
163
+ await tracing.dispose(); // Observation only; does not abort work or close the Harness.
164
+ // After every controller using this shared runtime has ended:
165
+ await runtime.shutdown();
166
+ ```
167
+
168
+ Create one observer per conversation and retain submission IDs for explicit reconciliation after gaps.
169
+ Late attachment and overflow provide snapshots, not complete event replay; interrupted observations are marked uncertain.
170
+ Tracing never resumes paused recovery or controls execution, and capture bounds never change execution data.
171
+ See the installed [durable API guide](./docs/durable.md) for the compatibility matrix, ownership, per-request correlation, privacy projections, recovery semantics and limitations.
172
+ The host remains responsible for authorization, storage, execution cancellation/recovery, callback-owned work and shared-runtime shutdown.
173
+
174
+ ## ⚙️ Settings
175
+
176
+ Settings apply to the Pi agent directory, not a project or an individual conversation. Edit `<getAgentDir()>/pi-otel.json` (normally `~/.pi/agent/pi-otel.json`).
177
+ If that file is absent, `pi-otel` reads a legacy `pi-langfuse.json` in the same directory without copying or deleting it.
178
+ An existing `pi-otel.json` always wins, even if invalid; repair it to re-enable tracing.
179
+ To edit a legacy setup with `/otel`, move the file to `pi-otel.json` first, without overwriting an existing file.
180
+
181
+ Keep the file private (`chmod 600 ~/.pi/agent/pi-otel.json`). The extension enforces mode `0600` and refuses to load the file if it cannot do so.
182
+ Restart each Pi process to change the backend, endpoint, credentials, or service name; `/reload` cannot replace the process-owned exporter.
183
+ The extension reads `captureContent` and `userId` again at session start. If set, `userId` is exported and must be a non-empty string of at most 200 characters.
184
+
185
+ ### OTLP collector
186
+
187
+ Use `"backend": "otlp"` with the full HTTP or HTTPS traces URL, including the receiver path (usually `/v1/traces`).
188
+ The exporter sends OTLP/HTTP protobuf, not gRPC. The URL must not contain credentials, a query, or a fragment.
189
+ Optional `serviceName` defaults to `pi`. Optional `headers` is an object of literal header names and values, for example `{"Authorization": "Bearer YOUR_TOKEN"}`.
190
+ Header names are case-insensitive and cannot be duplicated or override transport headers such as `Content-Type`.
191
+ The exporter does not inherit ambient `OTEL_EXPORTER_OTLP_*` connection settings. `captureContent` defaults to `false`.
192
+
193
+ ### Langfuse
194
+
195
+ Use `"backend": "langfuse"` or omit `backend` as in existing settings. Choose the Langfuse setup action in `/otel`, or save the literal keys manually:
196
+
197
+ ```json
198
+ {
199
+ "publicKey": "pk-lf-...",
200
+ "secretKey": "sk-lf-...",
201
+ "baseUrl": "https://us.cloud.langfuse.com",
202
+ "captureContent": false
203
+ }
204
+ ```
205
+
206
+ `publicKey` and `secretKey` are required. `baseUrl` defaults to `https://us.cloud.langfuse.com`; regional and self-hosted HTTP or HTTPS endpoints are supported.
207
+ Optional `environment` is at most 40 lowercase letters, numbers, hyphens, or underscores and cannot start with `langfuse`; `release` is an optional string.
208
+ Changes to `environment` or `release` also require a restart. For compatibility, `captureContent` defaults to `true` in Langfuse mode; set it to `false` to keep raw content local.
209
+
210
+ The setup flow leaves saved keys unchanged if you submit an empty key field. A blank base URL selects the default. Saves run in order within one Pi process, preserve unknown fields, and publish atomically. Invalid settings block writes; a failed save leaves the previous file and current session unchanged.
211
+
212
+ Use Langfuse Cloud or self-hosted Langfuse >=4.59.0 for [v4 OTLP ingestion](https://langfuse.com/integrations/native/opentelemetry). Compression defaults to `gzip` after checking `LANGFUSE_OTEL_COMPRESSION`, `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION`, and `OTEL_EXPORTER_OTLP_COMPRESSION` in order for a valid `gzip` or `none` value.
213
+
214
+ ## 🔭 What is traced
215
+
216
+ Both backends preserve the same run, attempt, turn, generation, tool, and compaction hierarchy. Langfuse keeps its existing `langfuse.*` ingestion attributes. A generic receiver gets standard OTLP spans with `service.name`, OpenTelemetry error status, and Pi attributes under `pi.observation.*` and `pi.trace.*`.
217
+
218
+ ```text
219
+ pi.trace
220
+ └── pi.agent (agent: submitted prompt until Pi fully settles)
221
+ ├── pi.attempt (span: one agent_start/agent_end pair)
222
+ │ └── pi.turn (span)
223
+ │ ├── pi.llm (generation)
224
+ │ └── pi.tool.<tool-name> (tool)
225
+ ├── pi.compaction (span, only while the trace is active)
226
+ └── pi.attempt ...
227
+ ```
228
+
229
+ All observations and the trace use schema version `2`.
230
+ Schema version 2 adds indexed `pi.attempt` observations and active `pi.compaction` spans beneath the root agent.
231
+
232
+ ### Trace and attempt fields
233
+
234
+ The trace and root `pi.agent` retain the submitted prompt, final assistant output, Pi session id, working directory, mode, initial provider/model, and optional Git context.
235
+ Root metadata includes:
236
+
237
+ - `pi.trace.schema_version`, `pi.trace.outcome`, and `pi.trace.stop_reason`;
238
+ - `pi.trace.attempt_count`, `pi.trace.turn_count`, `pi.trace.generation_count`, `pi.trace.tool_count`, `pi.trace.tool_error_count`, `pi.trace.compaction_count`, and `pi.trace.recovered_error_count`;
239
+ - `pi.trace.start_leaf_id`, `pi.trace.end_leaf_id`, `pi.trace.start_context_tokens`, `pi.trace.end_context_tokens`, `pi.trace.start_context_window`, `pi.trace.end_context_window`, `pi.trace.start_context_percent`, and `pi.trace.end_context_percent` when Pi knows them;
240
+ - `pi.git.branch`, `pi.git.commit`, and `pi.git.detached`, plus a `branch:<branch-name>` tag or `git:detached` tag.
241
+
242
+ Outcomes are `success`, `recovered_success`, `error`, `aborted`, `length`, or `interrupted`.
243
+ `pi.trace.recovered_error_count` includes recovered provider responses, tool failures handled by a later generation, and failed attempts followed by final success.
244
+ Errors use Langfuse `ERROR`; aborts, output limits, shutdown, replacement, and other interruption closures use `WARNING`.
245
+ High-cardinality correlation values stay in metadata rather than tags.
246
+
247
+ Each `pi.attempt` records `pi.attempt.index`, final `pi.attempt.outcome`, and `pi.attempt.stop_reason`.
248
+ An attempt immediately following overflow compaction also sets `pi.attempt.reason` to `post_compaction`.
249
+ Failed attempts remain errors even when a later attempt makes the root a recovered success.
250
+
251
+ ### Generation fields
252
+
253
+ Each `pi.llm` generation records:
254
+
255
+ - a bounded input snapshot from this extension's `before_provider_request` handler and `pi.request.payload_stage` set to `before_provider_request`;
256
+ - `pi.request.provider`, `pi.request.model`, `pi.request.api`, and `pi.request.thinking_level`, with thinking level also exported through Langfuse-native model parameters;
257
+ - the Langfuse-native response model plus `pi.response.provider`, `pi.response.api`, `pi.response.model`, and `pi.response.id` when Pi reports them;
258
+ - Langfuse-native `completionStartTime` from the first non-empty text, thinking, or tool-call delta;
259
+ - ordered `http.response.status_codes`, final `http.response.status_code`, `http.response.attempt_count`, and `http.response.retry_count`;
260
+ - allowlisted `http.response.headers`: request ids, `cf-ray`, `retry-after`, and the supported OpenAI/Anthropic rate-limit headers.
261
+ Authorization, cookies, and unrecognized headers are never exported;
262
+ - additive input, output, cache-read, cache-write, and total token usage plus known positive component costs and the best available total cost;
263
+ - non-additive `pi.usage.reasoning_tokens` and `pi.usage.cache_write_1h_tokens` in metadata so subsets are not double-counted.
264
+
265
+ A finite zero total is exported only when Pi reports `cost.totalFromProvider === true`, even when catalog-estimated component costs are positive.
266
+ Neither adapter replaces the total with the sum of component estimates.
267
+ When provenance is absent or false, zero cost buckets remain omitted to preserve the existing unknown-pricing fallback.
268
+ Boolean provenance is exported as `pi.usage.cost.total_from_provider` metadata, not as a numeric cost bucket; absent or invalid provenance stays omitted.
269
+ The durable adapter uses the same metadata key for assistant and nested-tool usage, while retaining its existing non-negative cost buckets, including zero totals regardless of provenance.
270
+
271
+ The request snapshot is the payload visible to this handler, not a guaranteed final wire payload.
272
+ A later extension can still replace it.
273
+ Final assistant content is reconciled from `turn_end` and `agent_end` after message transformation.
274
+ A recovered sequence such as `429 -> 200` remains queryable in HTTP metadata but is not an error; the final assistant outcome decides generation severity.
275
+ A provider request becomes a `pi.llm` generation only when Pi emits an assistant lifecycle event.
276
+ Cache-warming requests emit provider hooks without that lifecycle, so they are excluded instead of becoming orphaned or interrupted ordinary generations.
277
+ Dedicated cache-warm observations are deferred until Pi exposes a deterministic request-kind and completion signal.
278
+
279
+ ### Tool and compaction fields
280
+
281
+ A `pi.tool.<tool-name>` observation starts with raw `tool_execution_start` arguments as a fallback for calls that never execute, including calls blocked during `tool_call`.
282
+ For executed calls, it uses the `tool_result` input as authoritative after all argument mutations.
283
+ It captures final transformed output from `tool_execution_end`, final error state, `pi.tool.progress_update_count`, and `pi.tool.time_to_first_progress_ms` when progress occurs.
284
+ An unrecovered tool failure also makes the attempt and root errors.
285
+ Existing `pi.tool.call_id` and `pi.tool.name` correlation fields remain.
286
+ `tool_execution_update` partial-result bodies are never captured.
287
+ Duplicate, parallel, failed, no-progress, and interrupted tools are closed independently.
288
+
289
+ An active `pi.compaction` records its reason, retry state, source, token count, message counts, branch-entry count, and split-turn state.
290
+ The exported field names are `pi.compaction.reason`, `pi.compaction.will_retry`, `pi.compaction.from_extension`, `pi.compaction.tokens_before`, `pi.compaction.messages_to_summarize`, `pi.compaction.turn_prefix_messages`, `pi.compaction.branch_entries`, and `pi.compaction.is_split_turn`.
291
+ It adds `pi.compaction.read_file_count`, `pi.compaction.modified_file_count`, and `pi.compaction.usage.*` / `pi.compaction.cost.*` when Pi reports them.
292
+ Compaction costs use the same zero-total rules as generations and export boolean provenance as `pi.compaction.cost.total_from_provider` metadata.
293
+ It never records the summary, custom instructions, or message bodies.
294
+ Manual compaction outside an active agent trace is ignored; incomplete compaction closes as a warning at settlement or shutdown.
295
+
296
+ ### Boundaries and export
297
+
298
+ Images and embedded base64 data URIs are represented without their payloads, including provider data URLs.
299
+ Opaque `thinkingSignature`, `textSignature`, and `thoughtSignature` continuity values are always removed.
300
+ Every captured input or output has one cumulative 64 KiB serialized UTF-8 budget, bounded object/array traversal, and deterministic truncation markers.
301
+ The OpenTelemetry backend masks configured export credentials before writing span attributes.
302
+ Trace and observation fields, such as output and usage, take priority if there is too much metadata to export.
303
+
304
+ The root agent begins before the first agent loop and remains open across retries, overflow-compaction recovery, and queued continuations.
305
+ `agent_end` closes only the current attempt; `agent_settled` closes the root after no automatic work remains.
306
+ Activity that unexpectedly arrives without a submitted prompt gets a fallback root input labeled `[automatic continuation]`.
307
+ Session replacement, reload, quit, and a new unexpected prompt close all descendants defensively and idempotently.
308
+
309
+ At run start, the extension performs bounded, non-shell Git lookups in `ctx.cwd`.
310
+ A branch switch therefore applies to the next run.
311
+ Detached HEADs retain only commit/detached metadata and the `git:detached` tag.
312
+ Missing Git, non-repositories, timeouts, and lookup failures silently omit Git context without affecting tracing.
313
+
314
+ Completed observations are exported in batches while Pi remains live.
315
+ Neither `agent_end` nor `agent_settled` waits for exporter network I/O.
316
+ Quit shutdown drains the provider.
317
+
318
+ ## 💬 Commands
319
+
320
+ - `/otel` shows tracing status, the settings path, and privacy help. Use its setup action for Langfuse or edit the displayed settings file for a generic OTLP receiver. When tracing is active, choose **Flush completed traces for this session** to send completed spans to the configured endpoint. No arguments are accepted.
321
+ - `/langfuse` is deprecated. It warns you to use `/otel`, then opens the same menu and ignores arguments. This does not deprecate the Langfuse backend or its settings.
322
+
323
+ Both commands can open menus in TUI and RPC mode. Print and JSON modes reject them with the current status and settings path.
324
+
325
+ ## 🔒 Security and privacy
326
+
327
+ With content capture enabled, traces can contain user prompts, model responses, tool arguments, and tool results.
328
+ These may include source code, file contents, shell output, or other sensitive project data.
329
+ Review the destination's retention and access controls before enabling the extension. Use HTTPS for remote receivers because HTTP does not encrypt credentials or trace data.
330
+
331
+ Metadata includes Git branch names, commit ids, working directory, session and leaf ids, the configured `userId`, model identity, usage, cost, aggregate counts, and allowlisted response-header values.
332
+ This metadata remains exported when `captureContent` is `false`.
333
+ Branch names and diagnostic header values can contain operational details.
334
+ A `userId` can identify you if you set it to an email address or real name.
335
+ Choose a pseudonymous value when that matters, or leave `userId` unset to export no user at all.
336
+
337
+ The built-in mask protects configured export credentials but is not a general secret scanner.
338
+ Set `"captureContent": false` when prompts, provider-request snapshots, responses, and tool content must stay local. Turn it on only for trusted receivers.
339
+ Compaction summaries, tool partial results, opaque continuation signatures, authorization headers, cookies, and unapproved response headers are never exported in either mode.
340
+
341
+ ## 🗂️ Package layout
342
+
343
+ ```text
344
+ packages/pi-otel/
345
+ ├── src/ # Authoritative implementation and helpers
346
+ │ ├── index.ts # Thin default and public entrypoint
347
+ │ ├── otel.ts # Default settings and command adapter
348
+ │ ├── pi-session.ts # Per-session Pi lifecycle controller
349
+ │ ├── durable.ts # Public durable observer entrypoint
350
+ │ ├── runtime-core.ts # Process-runtime ownership
351
+ │ ├── runtime.ts # Lazy OpenTelemetry exporters and span mapping
352
+ │ └── tracing.ts # Schema-v2 observation recorder
353
+ ├── docs/durable.md # Durable API, compatibility and privacy contract
354
+ ├── dist/ # Generated Node, declaration, and Jiti runtime
355
+ ├── scripts/build-runtime.mjs # Runtime builder
356
+ └── test/ # Behavior and lifecycle coverage
357
+ ```
358
+
359
+ The generated extension runtime is built from `src/index.ts`; the Node library also builds `src/durable.ts` as a separate public entry.
360
+ Neither generated runtime imports back into `src`.
361
+
362
+ ## 🔎 Keywords
363
+
364
+ Pi extension, Pi coding agent, Langfuse, LLM observability, OpenTelemetry, tracing, generations, tool spans, token usage, AI agent monitoring.
365
+
366
+ ## 📄 License
367
+
368
+ MIT.
369
+ See [`LICENSE`](./LICENSE).