@narumitw/pi-otel 0.0.0-stage → 0.55.0

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 +170 -0
  2. package/LICENSE +21 -0
  3. package/README.md +371 -2
  4. package/dist/chunks/chunk-IXR5MVGN.ts +156 -0
  5. package/dist/chunks/chunk-IXR5MVGN.ts.map +7 -0
  6. package/dist/chunks/runtime-KWIFBNQ2.ts +404 -0
  7. package/dist/chunks/runtime-KWIFBNQ2.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 +1736 -0
  18. package/dist/index.js.map +7 -0
  19. package/dist/index.ts +1878 -0
  20. package/dist/index.ts.map +7 -0
  21. package/dist/library-chunks/chunk-BBL32ZV5.js +84 -0
  22. package/dist/library-chunks/chunk-BBL32ZV5.js.map +7 -0
  23. package/dist/library-chunks/chunk-ROM6FIM7.js +78 -0
  24. package/dist/library-chunks/chunk-ROM6FIM7.js.map +7 -0
  25. package/dist/library-chunks/chunk-ZCEZBO2T.js +158 -0
  26. package/dist/library-chunks/chunk-ZCEZBO2T.js.map +7 -0
  27. package/dist/library-chunks/runtime-7TSAKORH.js +406 -0
  28. package/dist/library-chunks/runtime-7TSAKORH.js.map +7 -0
  29. package/dist/otel.d.ts +13 -0
  30. package/dist/otlp-settings.d.ts +9 -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 +199 -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 +80 -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 +946 -0
package/src/config.ts ADDED
@@ -0,0 +1,330 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
3
+ import { dirname, join } from "node:path";
4
+ import { getAgentDir } from "@earendil-works/pi-coding-agent";
5
+
6
+ import { normalizeOtlpConnection, type OtlpConnection } from "./otlp-settings.js";
7
+ import { DEFAULT_BASE_URL } from "./runtime-defaults.js";
8
+
9
+ export { DEFAULT_BASE_URL } from "./runtime-defaults.js";
10
+
11
+ const CONFIG_FILE_NAME = "pi-otel.json";
12
+ const LEGACY_CONFIG_FILE_NAME = "pi-langfuse.json";
13
+
14
+ export interface LangfuseConfig {
15
+ backend?: "langfuse";
16
+ publicKey: string;
17
+ secretKey: string;
18
+ baseUrl: string;
19
+ environment?: string;
20
+ release?: string;
21
+ userId?: string;
22
+ captureContent: boolean;
23
+ }
24
+
25
+ export type LangfuseConfigPatch = Partial<LangfuseConfig>;
26
+
27
+ interface OtlpSettings extends OtlpConnection {
28
+ backend: "otlp";
29
+ captureContent: boolean;
30
+ userId?: string;
31
+ }
32
+
33
+ export type TracingSettings = LangfuseConfig | OtlpSettings;
34
+ type NormalizedSettings<T> = { ok: true; config: T } | { ok: false; reason: string };
35
+ export type SettingsResult = NormalizedSettings<TracingSettings> & {
36
+ path: string;
37
+ warnings: string[];
38
+ missing?: true;
39
+ legacy?: true;
40
+ };
41
+
42
+ export function otelSettingsPath(): string {
43
+ return join(getAgentDir(), CONFIG_FILE_NAME);
44
+ }
45
+
46
+ const configSaveQueues = new Map<string, Promise<void>>();
47
+
48
+ export function writeLangfuseConfig(patch: LangfuseConfigPatch, path = otelSettingsPath()): Promise<LangfuseConfig> {
49
+ const previous = configSaveQueues.get(path) ?? Promise.resolve();
50
+ const operation = previous.then(() => writeLangfuseConfigNow(patch, path));
51
+ const tail = operation.then(
52
+ () => undefined,
53
+ () => undefined,
54
+ );
55
+ configSaveQueues.set(path, tail);
56
+ void tail.then(() => {
57
+ if (configSaveQueues.get(path) === tail) configSaveQueues.delete(path);
58
+ });
59
+ return operation;
60
+ }
61
+
62
+ async function writeLangfuseConfigNow(patch: LangfuseConfigPatch, path: string): Promise<LangfuseConfig> {
63
+ const currentDocument = await readLangfuseDocumentForUpdate(path);
64
+ const normalized = normalizeLangfuseConfig({ ...currentDocument, ...patch });
65
+ if (!normalized.ok) throw new Error(normalized.reason);
66
+ const {
67
+ publicKey: _publicKey,
68
+ secretKey: _secretKey,
69
+ baseUrl: _baseUrl,
70
+ environment: _environment,
71
+ release: _release,
72
+ userId: _userId,
73
+ captureContent: _captureContent,
74
+ ...unknownFields
75
+ } = currentDocument;
76
+ const nextDocument = { ...unknownFields, ...normalized.config };
77
+
78
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 });
79
+ const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
80
+ try {
81
+ await writeFile(tempPath, `${JSON.stringify(nextDocument, null, 2)}\n`, {
82
+ encoding: "utf8",
83
+ mode: 0o600,
84
+ });
85
+ await chmod(tempPath, 0o600);
86
+ await rename(tempPath, path);
87
+ return normalized.config;
88
+ } catch (error) {
89
+ await rm(tempPath, { force: true }).catch(() => undefined);
90
+ throw error;
91
+ }
92
+ }
93
+
94
+ async function readLangfuseDocumentForUpdate(path: string): Promise<Record<string, unknown>> {
95
+ let parsed: unknown;
96
+ try {
97
+ parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
98
+ } catch (error) {
99
+ if (isNodeError(error) && error.code === "ENOENT") return {};
100
+ throw new Error(
101
+ `Cannot update ${CONFIG_FILE_NAME} because the existing file is malformed or unreadable; repair it first.`,
102
+ );
103
+ }
104
+ const normalized = normalizeLangfuseConfig(parsed);
105
+ if (!normalized.ok) {
106
+ throw new Error(
107
+ `Cannot update ${CONFIG_FILE_NAME} because the existing file has invalid recognized fields; repair it first.`,
108
+ );
109
+ }
110
+ return { ...(parsed as Record<string, unknown>) };
111
+ }
112
+
113
+ export async function loadSettings(path = otelSettingsPath()): Promise<SettingsResult> {
114
+ const current = await readSettings(path, normalizeSettings);
115
+ if (!current.missing || path !== otelSettingsPath()) return current;
116
+
117
+ // Read legacy Langfuse credentials without creating or replacing the canonical file.
118
+ const legacy = await readSettings(join(dirname(path), LEGACY_CONFIG_FILE_NAME), normalizeLangfuseConfig);
119
+ // A concurrent setup can create the canonical file while the legacy read is in flight.
120
+ const latest = await readSettings(path, normalizeSettings);
121
+ return latest.missing && !legacy.missing ? { ...legacy, legacy: true } : latest;
122
+ }
123
+
124
+ async function readSettings(
125
+ path: string,
126
+ normalize: (value: unknown) => NormalizedSettings<TracingSettings>,
127
+ ): Promise<SettingsResult> {
128
+ await configSaveQueues.get(path);
129
+ const warnings: string[] = [];
130
+ const permissionFailure = await ensurePrivatePermissions(path, warnings);
131
+ if (permissionFailure) {
132
+ return {
133
+ ok: false,
134
+ path,
135
+ warnings,
136
+ reason: `Refusing to load credentials: ${permissionFailure}`,
137
+ };
138
+ }
139
+
140
+ let text: string;
141
+ try {
142
+ text = await readFile(path, "utf8");
143
+ } catch (error) {
144
+ if (isNodeError(error) && error.code === "ENOENT") {
145
+ return { ok: false, path, warnings, missing: true, reason: `Configuration file not found: ${path}` };
146
+ }
147
+ return {
148
+ ok: false,
149
+ path,
150
+ warnings,
151
+ reason: `Failed to read ${path}: ${formatError(error)}`,
152
+ };
153
+ }
154
+
155
+ let parsed: unknown;
156
+ try {
157
+ parsed = JSON.parse(text) as unknown;
158
+ } catch {
159
+ return {
160
+ ok: false,
161
+ path,
162
+ warnings,
163
+ reason: `Failed to parse ${path} as JSON; repair the file before retrying.`,
164
+ };
165
+ }
166
+
167
+ const normalized = normalize(parsed);
168
+ if (!normalized.ok) return { ok: false, path, warnings, reason: normalized.reason };
169
+ return { ok: true, config: normalized.config, path, warnings };
170
+ }
171
+
172
+ function normalizeSettings(value: unknown): NormalizedSettings<TracingSettings> {
173
+ if (!isSettingsObject(value) || value.backend !== "otlp") return normalizeLangfuseConfig(value);
174
+ if (value.publicKey !== undefined || value.secretKey !== undefined || value.baseUrl !== undefined) {
175
+ return { ok: false, reason: "OTLP settings cannot contain Langfuse credentials or a Langfuse baseUrl." };
176
+ }
177
+ const common = normalizeCommonSettings(value, false);
178
+ if (!common.ok) return common;
179
+ try {
180
+ return { ok: true, config: { backend: "otlp", ...normalizeOtlpConnection(value), ...common.config } };
181
+ } catch (error) {
182
+ return { ok: false, reason: formatError(error) };
183
+ }
184
+ }
185
+
186
+ export function normalizeLangfuseConfig(value: unknown): NormalizedSettings<LangfuseConfig> {
187
+ if (!isSettingsObject(value)) {
188
+ return { ok: false, reason: `${CONFIG_FILE_NAME} must contain a JSON object.` };
189
+ }
190
+ const input = value;
191
+ if (input.backend !== undefined && input.backend !== "langfuse") {
192
+ return { ok: false, reason: 'Expected a Langfuse configuration with backend "langfuse" or no backend.' };
193
+ }
194
+ const publicKey = normalizeString(input.publicKey);
195
+ const secretKey = normalizeString(input.secretKey);
196
+ if (!publicKey) {
197
+ return { ok: false, reason: "Langfuse settings require a literal publicKey string." };
198
+ }
199
+ if (!secretKey) {
200
+ return { ok: false, reason: "Langfuse settings require a literal secretKey string." };
201
+ }
202
+ if (isInterpolation(publicKey)) {
203
+ return {
204
+ ok: false,
205
+ reason: "Langfuse publicKey must be literal; environment and command interpolation are not supported.",
206
+ };
207
+ }
208
+ if (isInterpolation(secretKey)) {
209
+ return {
210
+ ok: false,
211
+ reason: "Langfuse secretKey must be literal; environment and command interpolation are not supported.",
212
+ };
213
+ }
214
+
215
+ const rawBaseUrl = input.baseUrl === undefined ? DEFAULT_BASE_URL : normalizeString(input.baseUrl);
216
+ if (!rawBaseUrl) {
217
+ return { ok: false, reason: "Langfuse baseUrl must be a non-empty string." };
218
+ }
219
+ const baseUrl = normalizeBaseUrl(rawBaseUrl);
220
+ if (!baseUrl) {
221
+ return {
222
+ ok: false,
223
+ reason: "Langfuse baseUrl must use HTTP or HTTPS without credentials, a query, or a fragment.",
224
+ };
225
+ }
226
+
227
+ const common = normalizeCommonSettings(input, true);
228
+ if (!common.ok) return common;
229
+ const environment = optionalString(input.environment, "environment");
230
+ if (!environment.ok) return environment;
231
+ if (environment.value && (environment.value.length > 40 || !/^(?!langfuse)[a-z0-9_-]+$/u.test(environment.value))) {
232
+ return {
233
+ ok: false,
234
+ reason:
235
+ "Langfuse environment must be at most 40 lowercase letters, numbers, hyphens, or underscores and must not start with langfuse.",
236
+ };
237
+ }
238
+ const release = optionalString(input.release, "release");
239
+ if (!release.ok) return release;
240
+
241
+ return {
242
+ ok: true,
243
+ config: {
244
+ publicKey,
245
+ secretKey,
246
+ baseUrl,
247
+ ...(environment.value ? { environment: environment.value } : {}),
248
+ ...(release.value ? { release: release.value } : {}),
249
+ ...common.config,
250
+ },
251
+ };
252
+ }
253
+
254
+ function normalizeCommonSettings(
255
+ input: Record<string, unknown>,
256
+ captureByDefault: boolean,
257
+ ): NormalizedSettings<Pick<TracingSettings, "userId" | "captureContent">> {
258
+ if (input.captureContent !== undefined && typeof input.captureContent !== "boolean") {
259
+ return { ok: false, reason: "captureContent must be a boolean." };
260
+ }
261
+ const userId = optionalString(input.userId, "userId");
262
+ if (!userId.ok) return userId;
263
+ if (userId.value && userId.value.length > 200) {
264
+ return { ok: false, reason: "userId must be at most 200 characters." };
265
+ }
266
+ return {
267
+ ok: true,
268
+ config: {
269
+ captureContent: input.captureContent ?? captureByDefault,
270
+ ...(userId.value ? { userId: userId.value } : {}),
271
+ },
272
+ };
273
+ }
274
+
275
+ function isSettingsObject(value: unknown): value is Record<string, unknown> {
276
+ return !!value && typeof value === "object" && !Array.isArray(value);
277
+ }
278
+
279
+ async function ensurePrivatePermissions(path: string, warnings: string[]): Promise<string | undefined> {
280
+ try {
281
+ const file = await stat(path);
282
+ if ((file.mode & 0o777) !== 0o600) {
283
+ await chmod(path, 0o600);
284
+ const repaired = await stat(path);
285
+ if ((repaired.mode & 0o777) !== 0o600) {
286
+ throw new Error(`permissions remained ${(repaired.mode & 0o777).toString(8)}`);
287
+ }
288
+ warnings.push(`Restricted ${path} permissions to 0600.`);
289
+ }
290
+ } catch (error) {
291
+ if (isNodeError(error) && error.code === "ENOENT") return undefined;
292
+ const failure = `Failed to enforce 0600 permissions for ${path}: ${formatError(error)}`;
293
+ warnings.push(failure);
294
+ return failure;
295
+ }
296
+ return undefined;
297
+ }
298
+
299
+ function normalizeBaseUrl(value: string): string | undefined {
300
+ try {
301
+ const url = new URL(value);
302
+ if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
303
+ if (url.username || url.password || url.search || url.hash) return undefined;
304
+ return url.toString().replace(/\/+$/, "");
305
+ } catch {
306
+ return undefined;
307
+ }
308
+ }
309
+
310
+ function optionalString(value: unknown, name: string): { ok: true; value?: string } | { ok: false; reason: string } {
311
+ if (value === undefined) return { ok: true };
312
+ const normalized = normalizeString(value);
313
+ return normalized ? { ok: true, value: normalized } : { ok: false, reason: `${name} must be a non-empty string.` };
314
+ }
315
+
316
+ function normalizeString(value: unknown): string | undefined {
317
+ return typeof value === "string" && value.trim() ? value.trim() : undefined;
318
+ }
319
+
320
+ function isInterpolation(value: string): boolean {
321
+ return value.startsWith("$") || value.startsWith("!");
322
+ }
323
+
324
+ function isNodeError(error: unknown): error is NodeJS.ErrnoException {
325
+ return error instanceof Error && "code" in error;
326
+ }
327
+
328
+ function formatError(error: unknown): string {
329
+ return error instanceof Error ? error.message : String(error);
330
+ }
@@ -0,0 +1,112 @@
1
+ import type { EntryRecord } from "@earendil-works/pi-durable";
2
+ import { sanitizeTraceValue } from "./sanitizer.js";
3
+ import type { ObservationAttributes } from "./tracing.js";
4
+
5
+ type Message = NonNullable<EntryRecord["model"]>[number];
6
+ const MAX_PROJECTED_ITEMS = 199;
7
+
8
+ export function durableAttributes(attributes: ObservationAttributes): ObservationAttributes {
9
+ const copy = { ...attributes };
10
+ if (attributes.metadata) {
11
+ const value = sanitizeTraceValue(attributes.metadata, true);
12
+ copy.metadata =
13
+ value && typeof value === "object" && !Array.isArray(value)
14
+ ? (value as Record<string, unknown>)
15
+ : { "pi.durable.metadata_omitted": true };
16
+ }
17
+ for (const key of ["name", "model", "sessionId", "userId", "statusMessage", "version"] as const) {
18
+ if (typeof copy[key] === "string") copy[key] = String(sanitizeTraceValue(copy[key], true));
19
+ }
20
+ return copy;
21
+ }
22
+
23
+ export function durableDiagnosticCount(entry: EntryRecord | undefined): number {
24
+ const data = entry?.data;
25
+ return data &&
26
+ typeof data === "object" &&
27
+ !Array.isArray(data) &&
28
+ "diagnostics" in data &&
29
+ Array.isArray(data.diagnostics)
30
+ ? data.diagnostics.length
31
+ : 0;
32
+ }
33
+
34
+ /** Project committed messages without provider configuration, deltas or raw diagnostics. */
35
+ export function durableContent(
36
+ messages: readonly Message[] | undefined,
37
+ capture: boolean,
38
+ diagnosticCount = 0,
39
+ ): unknown {
40
+ if (!capture) return "[content capture disabled]";
41
+ const projected: unknown[] | undefined = messages?.slice(0, MAX_PROJECTED_ITEMS).map((message) => {
42
+ if (message.role === "toolResult" && message.isError)
43
+ return { role: message.role, content: "[tool error content omitted]" };
44
+ if (message.role === "assistant" && message.stopReason === "error")
45
+ return { role: message.role, content: "[assistant error content omitted]" };
46
+ // The public ToolResultEntry shape appends rendered diagnostics as its last text block.
47
+ // That block can contain raw errors, headers or credentials even when the tool succeeds.
48
+ const omitDiagnosticBlock =
49
+ message.role === "toolResult" && diagnosticCount > 0 && message.content.at(-1)?.type === "text";
50
+ const blockCount = message.content.length - (omitDiagnosticBlock ? 1 : 0);
51
+ return {
52
+ role: message.role,
53
+ content:
54
+ typeof message.content === "string"
55
+ ? message.content
56
+ : message.content.slice(0, Math.min(MAX_PROJECTED_ITEMS, blockCount)).map((block) => {
57
+ switch (block.type) {
58
+ case "text":
59
+ return { type: "text", text: block.text };
60
+ case "thinking":
61
+ return { type: "thinking", thinking: block.thinking };
62
+ case "toolCall":
63
+ return { type: "toolCall", id: block.id, name: block.name, arguments: block.arguments };
64
+ case "image":
65
+ return { type: "image", mimeType: block.mimeType, data: "[base64 omitted]" };
66
+ default:
67
+ return { type: "unsupported", content: "[block omitted]" };
68
+ }
69
+ }),
70
+ ...(Array.isArray(message.content) && blockCount > MAX_PROJECTED_ITEMS
71
+ ? { blocksOmitted: blockCount - MAX_PROJECTED_ITEMS }
72
+ : {}),
73
+ ...(omitDiagnosticBlock ? { diagnosticsOmitted: diagnosticCount } : {}),
74
+ };
75
+ });
76
+ if (messages && messages.length > MAX_PROJECTED_ITEMS)
77
+ projected?.push({ messagesOmitted: messages.length - MAX_PROJECTED_ITEMS });
78
+ return sanitizeTraceValue(projected, true);
79
+ }
80
+
81
+ export function durableUsage(message: Message): ObservationAttributes {
82
+ if ((message.role !== "assistant" && message.role !== "toolResult") || !message.usage) return {};
83
+ const usageDetails: Record<string, number> = {};
84
+ const costDetails: Record<string, number> = {};
85
+ for (const [key, field] of [
86
+ ["input", "input"],
87
+ ["output", "output"],
88
+ ["cacheRead", "cache_read_input_tokens"],
89
+ ["cacheWrite", "cache_creation_input_tokens"],
90
+ ["totalTokens", "total"],
91
+ ] as const) {
92
+ const value = message.usage[key];
93
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) usageDetails[field] = value;
94
+ }
95
+ for (const [key, field] of [
96
+ ["input", "input"],
97
+ ["output", "output"],
98
+ ["cacheRead", "cache_read"],
99
+ ["cacheWrite", "cache_write"],
100
+ ["total", "total"],
101
+ ] as const) {
102
+ const value = message.usage.cost[key];
103
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) costDetails[field] = value;
104
+ }
105
+ return {
106
+ usageDetails,
107
+ costDetails,
108
+ ...(typeof message.usage.cost.totalFromProvider === "boolean"
109
+ ? { metadata: { "pi.usage.cost.total_from_provider": message.usage.cost.totalFromProvider } }
110
+ : {}),
111
+ };
112
+ }