@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/src/durable.ts ADDED
@@ -0,0 +1,364 @@
1
+ import type { Context } from "@earendil-works/chord";
2
+ import { awaitWithContext, withCancel } from "@earendil-works/chord/context";
3
+ import type {
4
+ CommitObservation,
5
+ ConversationId,
6
+ ConversationView,
7
+ Observation as DurableObservation,
8
+ EntryId,
9
+ Harness,
10
+ SubmissionId,
11
+ WatchEnd,
12
+ } from "@earendil-works/pi-durable";
13
+ import { type DurableCorrelation, DurableRecorder, type DurableRecorderOptions } from "./durable-recorder.js";
14
+ import {
15
+ advanceDurableSnapshot,
16
+ type DurableCommit,
17
+ type DurableSnapshot,
18
+ durableCommit,
19
+ durableSnapshot,
20
+ } from "./durable-state.js";
21
+ import { getLangfuseRuntimeInternal, type LangfuseRuntime } from "./runtime-core.js";
22
+
23
+ export type { DurableCorrelation } from "./durable-recorder.js";
24
+ export {
25
+ type CreateLangfuseRuntimeOptions,
26
+ createLangfuseRuntime,
27
+ createOtelRuntime,
28
+ type LangfuseRuntime,
29
+ type LangfuseRuntimeConfig,
30
+ type OtlpRuntimeConfig,
31
+ } from "./runtime-api.js";
32
+ export { createLangfuseRuntimeFromBackend } from "./runtime-core.js";
33
+ export type { Observation, ObservationAttributes, ObservationType, TraceBackend } from "./tracing.js";
34
+
35
+ export interface PiLangfuseDurableOptions extends Omit<DurableRecorderOptions, "conversationId" | "requestId"> {
36
+ harness: Harness;
37
+ conversationId: ConversationId;
38
+ /** Governs observation only. Cancellation never aborts execution or resumes recovery. */
39
+ context: Context;
40
+ }
41
+
42
+ export interface PiLangfuseDurableConversation {
43
+ readonly active: boolean;
44
+ /** Resolves after initialization, observer detachment, and owned delivery have joined. */
45
+ readonly closed: Promise<void>;
46
+ /** Read committed status without waiting for or starting agent work. Also supports late submission attachment. */
47
+ observeSubmission(id: SubmissionId, correlation?: DurableCorrelation): Promise<void>;
48
+ /** Detach and close observations, without flushing/shutting down the runtime or modifying durable work. */
49
+ dispose(): Promise<void>;
50
+ }
51
+
52
+ type Delivery =
53
+ | { kind: "commit"; commit: DurableCommit }
54
+ | { kind: "snapshot"; snapshot: DurableSnapshot }
55
+ | { kind: "submission"; id: SubmissionId; correlation?: DurableCorrelation; done: () => void };
56
+ const MAX_PENDING_PUBLICATIONS = 100;
57
+ const observedConversations = new WeakMap<Harness, Set<ConversationId>>();
58
+
59
+ /** Attach a fail-open, committed-only observer. The host remains the sole owner of execution. */
60
+ export async function createPiLangfuseDurableConversation(
61
+ runtime: LangfuseRuntime,
62
+ options: PiLangfuseDurableOptions,
63
+ ): Promise<PiLangfuseDurableConversation> {
64
+ options = { ...options };
65
+ const { context, cancel } = withCancel(options.context);
66
+ let view: DurableObservation<ConversationView> | undefined;
67
+ let commits: CommitObservation | undefined;
68
+ let latestView: DurableSnapshot | undefined;
69
+ let committed: DurableSnapshot | undefined;
70
+ let recorder: DurableRecorder | undefined;
71
+ let releaseRuntime: (() => void) | undefined;
72
+ let disposed = false;
73
+ let ready = false;
74
+ let sourceEnded = false;
75
+ let sourceClosing = false;
76
+ let sourceListenerError = false;
77
+ let recordingFailed = false;
78
+ let ownsConversation = false;
79
+ let initialization: Promise<void>;
80
+ let delivery: Promise<void> = Promise.resolve();
81
+ let scheduled = false;
82
+ let disposePromise: Promise<void> | undefined;
83
+ const pending: Delivery[] = [];
84
+ let pendingPublications = 0;
85
+ let resolveClosed!: () => void;
86
+ const closed = new Promise<void>((resolve) => {
87
+ resolveClosed = resolve;
88
+ });
89
+
90
+ function report(stage: string): void {
91
+ if (recorder) recorder.report(stage);
92
+ else {
93
+ try {
94
+ Promise.resolve(options.onError?.(stage)).catch(() => undefined);
95
+ } catch {
96
+ /* Fail open. */
97
+ }
98
+ }
99
+ }
100
+
101
+ async function readEntry(id: EntryId) {
102
+ if (disposed) return undefined;
103
+ const entry = await options.harness.commit((tx) => tx.entry(id), context);
104
+ return disposed ? undefined : entry;
105
+ }
106
+
107
+ async function reconcile(id: SubmissionId, correlation?: DurableCorrelation): Promise<void> {
108
+ if (disposed) return;
109
+ try {
110
+ const submission = await options.harness.submission(id, context);
111
+ if (disposed || !submission) return;
112
+ const record = await submission.status(context); // wait() would resume paused recovery.
113
+ if (disposed) return;
114
+ await recorder?.submission(record, readEntry, correlation, true);
115
+ } catch {
116
+ if (!disposed) report("submission status read");
117
+ }
118
+ }
119
+
120
+ function clearPending(): void {
121
+ for (const item of pending.splice(0)) if (item.kind === "submission") item.done();
122
+ pendingPublications = 0;
123
+ }
124
+
125
+ function schedule(): void {
126
+ if (disposed || scheduled) return;
127
+ scheduled = true;
128
+ // Source callbacks only record. Every exporter, callback and Session call runs after their stack unwinds.
129
+ delivery = Promise.resolve()
130
+ .then(drain)
131
+ .catch(() => {
132
+ if (!disposed) report("observer delivery");
133
+ })
134
+ .finally(() => {
135
+ scheduled = false;
136
+ if (!disposed && recorder && (pending.length || sourceEnded || recordingFailed)) schedule();
137
+ });
138
+ }
139
+
140
+ function enqueue(item: Delivery): void {
141
+ if (disposed) {
142
+ if (item.kind === "submission") item.done();
143
+ return;
144
+ }
145
+ if (item.kind !== "submission" && pendingPublications >= MAX_PENDING_PUBLICATIONS) {
146
+ // Overflow drops source history, never explicit host requests. Keep those requests in their original order;
147
+ // callers retain their pending promises as backpressure until reconciliation or cancellation joins them.
148
+ let retained = 0;
149
+ for (const queued of pending) if (queued.kind === "submission") pending[retained++] = queued;
150
+ pending.length = retained;
151
+ pendingPublications = 0;
152
+ if (committed) {
153
+ pending.push({ kind: "snapshot", snapshot: committed });
154
+ pendingPublications += 1;
155
+ }
156
+ // The overflowing commit is already in the replacement baseline. Do not replay its entries.
157
+ if (item.kind === "commit") {
158
+ schedule();
159
+ return;
160
+ }
161
+ }
162
+ pending.push(item);
163
+ if (item.kind !== "submission") pendingPublications += 1;
164
+ schedule();
165
+ }
166
+
167
+ async function drain(): Promise<void> {
168
+ if (!recorder || disposed) return;
169
+ if (recordingFailed) {
170
+ recordingFailed = false;
171
+ report("observer recording");
172
+ void dispose();
173
+ return;
174
+ }
175
+ while (!disposed) {
176
+ const item = pending.shift();
177
+ if (!item) break;
178
+ if (item.kind !== "submission") pendingPublications -= 1;
179
+ try {
180
+ if (item.kind === "commit") await recorder.commit(item.commit, readEntry);
181
+ else if (item.kind === "submission") await reconcile(item.id, item.correlation);
182
+ else {
183
+ recorder.snapshot(item.snapshot);
184
+ const ids = new Set([
185
+ ...recorder.submissionIds,
186
+ ...(item.snapshot.live.run?.inputs ?? []),
187
+ ...item.snapshot.inbox,
188
+ ]);
189
+ for (const id of ids) {
190
+ await reconcile(id);
191
+ if (disposed) break;
192
+ }
193
+ }
194
+ } catch {
195
+ if (!disposed) report("observer delivery");
196
+ } finally {
197
+ if (item.kind === "submission") item.done();
198
+ }
199
+ }
200
+ if (!disposed && sourceEnded) {
201
+ // Both synchronous observers end `failed` even on normal close. Only Harness.closed distinguishes a failed
202
+ // Session without parsing error prose. This is an observation-lifetime join, never an execution wait.
203
+ if (sourceListenerError) report("observer closure");
204
+ else if (sourceClosing) {
205
+ try {
206
+ const end = await awaitWithContext(options.harness.closed, context);
207
+ if (disposed) return;
208
+ if (end.kind === "failed") report("observer closure");
209
+ } catch {
210
+ if (!disposed) report("observer closure");
211
+ }
212
+ }
213
+ if (!disposed) void dispose();
214
+ }
215
+ }
216
+
217
+ function recordEnd(end: WatchEnd): void {
218
+ sourceEnded = true;
219
+ sourceClosing ||= end.kind === "failed";
220
+ sourceListenerError ||= end.kind === "listener_error";
221
+ schedule();
222
+ }
223
+
224
+ function observeSubmission(id: SubmissionId, correlation?: DurableCorrelation): Promise<void> {
225
+ return new Promise((done) => enqueue({ kind: "submission", id, correlation, done }));
226
+ }
227
+
228
+ function dispose(): Promise<void> {
229
+ if (disposePromise) return disposePromise;
230
+ // Publish the join before cancellation/exporter callbacks can reenter this method.
231
+ disposePromise = Promise.resolve().then(async () => {
232
+ await initialization;
233
+ await delivery;
234
+ if (ownsConversation) {
235
+ observedConversations.get(options.harness)?.delete(options.conversationId);
236
+ ownsConversation = false;
237
+ }
238
+ releaseRuntime?.();
239
+ releaseRuntime = undefined;
240
+ resolveClosed();
241
+ });
242
+ disposed = true;
243
+ ready = false;
244
+ cancel();
245
+ context.abortSignal?.removeEventListener("abort", onAbort);
246
+ clearPending();
247
+ try {
248
+ commits?.detach();
249
+ } catch {
250
+ report("observer stop");
251
+ }
252
+ try {
253
+ view?.detach();
254
+ } catch {
255
+ report("observer stop");
256
+ }
257
+ recorder?.dispose();
258
+ latestView = undefined;
259
+ committed = undefined;
260
+ return disposePromise;
261
+ }
262
+ function onAbort(): void {
263
+ void dispose();
264
+ }
265
+
266
+ const controller: PiLangfuseDurableConversation = {
267
+ get active() {
268
+ return !disposed && !runtime.closed && ready;
269
+ },
270
+ closed,
271
+ observeSubmission,
272
+ dispose,
273
+ };
274
+
275
+ async function initialize(): Promise<void> {
276
+ try {
277
+ context.abortSignal?.throwIfAborted();
278
+ const conversations = observedConversations.get(options.harness) ?? new Set<ConversationId>();
279
+ if (conversations.has(options.conversationId)) throw new Error("Conversation already observed.");
280
+ conversations.add(options.conversationId);
281
+ observedConversations.set(options.harness, conversations);
282
+ ownsConversation = true;
283
+ const internal = getLangfuseRuntimeInternal(runtime);
284
+ releaseRuntime = internal.registerSession(dispose);
285
+ context.abortSignal?.addEventListener("abort", onAbort, { once: true });
286
+ commits = options.harness.observeCommits({
287
+ advance(publication) {
288
+ if (disposed || !ready || !committed) return;
289
+ try {
290
+ const commit = durableCommit(publication, options.conversationId);
291
+ if (
292
+ !commit.live &&
293
+ !commit.inbox &&
294
+ !commit.entries.length &&
295
+ !commit.tasks.length &&
296
+ !commit.submissions.length
297
+ )
298
+ return;
299
+ committed = advanceDurableSnapshot(committed, commit);
300
+ enqueue({ kind: "commit", commit });
301
+ } catch {
302
+ recordingFailed = true;
303
+ schedule();
304
+ }
305
+ },
306
+ end: recordEnd,
307
+ });
308
+ const attached = await options.harness.observeConversation(
309
+ options.conversationId,
310
+ {
311
+ advance(call) {
312
+ if (disposed || ready || call.kind !== "value") return;
313
+ try {
314
+ latestView = durableSnapshot(call.value);
315
+ } catch {
316
+ recordingFailed = true;
317
+ }
318
+ },
319
+ end: recordEnd,
320
+ },
321
+ context,
322
+ );
323
+ view = attached;
324
+ if (disposed || runtime.closed) {
325
+ attached.detach();
326
+ void dispose();
327
+ return;
328
+ }
329
+ const initial = durableSnapshot(attached.value);
330
+ // The OUTER read-only commit promise joins earlier outcomes/publications; a table read alone does not.
331
+ // No await separates choosing this baseline and enabling stored delivery. Work before it is snapshot history,
332
+ // including callbacks made before observeConversation's attaching promise resolved.
333
+ await options.harness.commit((tx) => tx.conversation(options.conversationId), context);
334
+ if (disposed || runtime.closed) {
335
+ void dispose();
336
+ return;
337
+ }
338
+ if (sourceEnded || recordingFailed) throw new Error("Observation ended while attaching.");
339
+ const baseline = latestView ?? initial;
340
+ committed = baseline;
341
+ ready = true;
342
+ recorder = new DurableRecorder(internal.backend, { ...options, metadata: { ...options.metadata } });
343
+ if (disposed || runtime.closed) {
344
+ recorder.dispose();
345
+ void dispose();
346
+ return;
347
+ }
348
+ recorder.snapshot(baseline, true);
349
+ latestView = undefined;
350
+ const ids = new Set([...(baseline.live.run?.inputs ?? []), ...baseline.inbox]);
351
+ // No asynchronous publication can interleave with this synchronous trace acquisition.
352
+ const baselineReads = [...ids].map((id) => observeSubmission(id));
353
+ schedule();
354
+ await Promise.all(baselineReads);
355
+ } catch {
356
+ if (!disposed) report("observer initialization");
357
+ void dispose();
358
+ }
359
+ }
360
+ initialization = Promise.resolve().then(initialize);
361
+ await initialization;
362
+ if (disposed) await dispose();
363
+ return controller;
364
+ }
package/src/git.ts ADDED
@@ -0,0 +1,64 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import type { GitMetadata } from "./tracing.js";
3
+
4
+ const GIT_LOOKUP_TIMEOUT_MS = 1_000;
5
+ // A branch (at most 256 characters) or commit ID needs little output, including diagnostics.
6
+ const GIT_LOOKUP_MAX_BUFFER = 4 * 1024;
7
+ const MAX_GIT_BRANCH_LENGTH = 256;
8
+
9
+ type GitExecutor = ExtensionAPI["exec"];
10
+
11
+ export async function resolveGitMetadata(exec: GitExecutor, cwd: string): Promise<GitMetadata | undefined> {
12
+ const [branchResult, commit] = await Promise.all([resolveGitBranch(exec, cwd), resolveGitCommit(exec, cwd)]);
13
+ if (!branchResult.resolved) return undefined;
14
+ if (branchResult.branch) {
15
+ return {
16
+ branch: branchResult.branch,
17
+ ...(commit ? { commit } : {}),
18
+ detached: false,
19
+ };
20
+ }
21
+ return commit ? { commit, detached: true } : undefined;
22
+ }
23
+
24
+ async function resolveGitBranch(exec: GitExecutor, cwd: string): Promise<{ resolved: boolean; branch?: string }> {
25
+ try {
26
+ const result = await exec("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
27
+ cwd,
28
+ timeout: GIT_LOOKUP_TIMEOUT_MS,
29
+ maxBuffer: GIT_LOOKUP_MAX_BUFFER,
30
+ });
31
+ if (result.truncated || result.killed) return { resolved: false };
32
+ if (result.code === 1) return { resolved: true };
33
+ if (result.code !== 0) return { resolved: false };
34
+ const branch = normalizeGitBranch(result.stdout);
35
+ return branch ? { resolved: true, branch } : { resolved: false };
36
+ } catch {
37
+ return { resolved: false };
38
+ }
39
+ }
40
+
41
+ async function resolveGitCommit(exec: GitExecutor, cwd: string): Promise<string | undefined> {
42
+ try {
43
+ const result = await exec("git", ["rev-parse", "--verify", "--short=12", "HEAD"], {
44
+ cwd,
45
+ timeout: GIT_LOOKUP_TIMEOUT_MS,
46
+ maxBuffer: GIT_LOOKUP_MAX_BUFFER,
47
+ });
48
+ if (result.truncated || result.killed || result.code !== 0) return undefined;
49
+ const commit = result.stdout.trim();
50
+ return /^[0-9a-f]{4,64}$/iu.test(commit) ? commit.toLowerCase() : undefined;
51
+ } catch {
52
+ return undefined;
53
+ }
54
+ }
55
+
56
+ function normalizeGitBranch(value: string): string | undefined {
57
+ const branch = value.trim();
58
+ if (!branch || branch.length > MAX_GIT_BRANCH_LENGTH) return undefined;
59
+ for (const character of branch) {
60
+ const code = character.codePointAt(0) ?? 0;
61
+ if (code <= 31 || code === 127) return undefined;
62
+ }
63
+ return branch;
64
+ }
package/src/index.ts ADDED
@@ -0,0 +1,12 @@
1
+ export { default } from "./otel.js";
2
+ export {
3
+ type CreateLangfuseRuntimeOptions,
4
+ createLangfuseRuntime,
5
+ createOtelRuntime,
6
+ createPiLangfuseSession,
7
+ type LangfuseRuntime,
8
+ type LangfuseRuntimeConfig,
9
+ type OtlpRuntimeConfig,
10
+ type PiLangfuseSession,
11
+ type PiLangfuseSessionOptions,
12
+ } from "./public-api.js";