psyclaw 0.30.2 → 0.30.3

package/dist/src/observability/index.js

@@ -1,8 +1,18 @@
+import { arch, platform } from "node:os";
+import { PSYCLAW_VERSION } from "../branding.js";
 import { observabilityEnabled, readNodeObservabilityConfig, sanitizeAgentEventProperties, } from "./config.js";
+import { filesystemErrorContext, redactUserPath } from "./error-context.js";
+import { ensureAnonymousDistinctId, newAnonymousDistinctId } from "./identity.js";
+import { isExpectedUserError } from "./expected.js";
 import { readTelemetryPreference, resolveTelemetryEnabled, telemetryPreferenceOptions } from "./preference.js";
-export { DEFAULT_POSTHOG_HOST, OBS_CONFIG_SCRIPT_ID, browserConfigForPreference, emptyBrowserObservabilityConfig, injectBrowserObservabilityConfig, observabilityEnabled, readBrowserObservabilityConfig, readNodeObservabilityConfig, sanitizeAgentEventProperties, } from "./config.js";
-export { DEFAULT_TELEMETRY_PREFERENCE, parseTelemetryPreference, psyclawSettingsPath, readTelemetryEnvOverride, readTelemetryPreference, resolveTelemetryEnabled, shouldShowTelemetryNotice, telemetryPreferenceOptions, writeTelemetryPreference, } from "./preference.js";
+export { DEFAULT_LANGFUSE_HOST, DEFAULT_POSTHOG_HOST, OBS_CONFIG_SCRIPT_ID, browserConfigForPreference, emptyBrowserObservabilityConfig, injectBrowserObservabilityConfig, observabilityEnabled, readBrowserObservabilityConfig, readNodeObservabilityConfig, sanitizeAgentEventProperties, } from "./config.js";
+export { DEFAULT_TELEMETRY_PREFERENCE, parseAnonymousDistinctId, parseTelemetryPreference, psyclawSettingsPath, readTelemetryEnvOverride, readTelemetryPreference, resolveTelemetryEnabled, shouldShowTelemetryNotice, telemetryPreferenceOptions, writeTelemetryPreference, } from "./preference.js";
 export { maybeShowTelemetryNotice } from "./notice.js";
+export { ensureAnonymousDistinctId, newAnonymousDistinctId } from "./identity.js";
+export { filesystemErrorContext, fsWriteErrorMessage, redactUserPath } from "./error-context.js";
+export { extractPiGeneration, lastPiGeneration, posthogAiGenerationProperties } from "./llm.js";
+export { readLangfuseConfig } from "./langfuse.js";
+export { ExpectedUserError, isExpectedUserError, isExpectedUserErrorMessage } from "./expected.js";
 let bootPromise;
 let handle;
 async function defaultBoot(config) {
@@ -20,7 +30,15 @@ export async function initNodeObservability(options = {}) {
     if (!resolveTelemetryEnabled(preference, env)) {
         return handle !== undefined;
     }
-    const config = readNodeObservabilityConfig(env);
+    const distinctId = preference.anonymousId
+        ?? env.PSYCLAW_DISTINCT_ID?.trim()
+        ?? (options.preference !== undefined && options.settingsPath === undefined
+            ? newAnonymousDistinctId()
+            : await ensureAnonymousDistinctId(telemetryPreferenceOptions(options.settingsPath)));
+    const config = {
+        ...readNodeObservabilityConfig(env),
+        distinctId,
+    };
     // Disabled must not latch the singleton: tests and a later enable in the
     // same process still need to be able to boot.
     if (!observabilityEnabled(config)) {
@@ -44,16 +62,51 @@ export function trackAgentEvent(name, properties = {}) {
     return emitWhenReady((active) => active.captureEvent(name, safe));
 }
 export function captureAgentError(error, context = {}) {
-    const safeContext = {};
-    for (const [key, value] of Object.entries(context)) {
-        if (typeof value === "string" && value.trim())
-            safeContext[key] = value.trim().slice(0, 80);
+    if (isExpectedUserError(error))
+        return Promise.resolve();
+    const extracted = filesystemErrorContext(error);
+    const safeContext = {
+        package_version: PSYCLAW_VERSION,
+        os_platform: platform(),
+        os_arch: arch(),
+    };
+    for (const [key, value] of Object.entries({ ...extracted, ...context })) {
+        if (typeof value === "string" && value.trim()) {
+            const limit = key === "failed_path" || key === "cwd" ? 240 : 80;
+            const next = key === "failed_path" || key === "cwd" ? redactUserPath(value.trim()) : value.trim();
+            safeContext[key] = next.slice(0, limit);
+        }
     }
     return emitWhenReady((active) => active.captureError(error, safeContext));
 }
 export function trackGateWaiting(gate) {
     return trackAgentEvent("gate_waiting_for_human", { phase: "gate", gate, status: "waiting" });
 }
+export function trackSkillInstall(status, properties = {}) {
+    return trackAgentEvent(`skill_install_${status === "queued" ? "queued" : status === "started" ? "started" : status === "error" ? "failed" : "finished"}`, {
+        phase: "skill_install",
+        status,
+        ...properties,
+    });
+}
+export function trackLlmGeneration(input) {
+    return emitWhenReady((active) => {
+        if (typeof active.captureLlmGeneration === "function")
+            active.captureLlmGeneration(input);
+    });
+}
+export async function withAgentSpan(name, attributes, fn) {
+    try {
+        if (bootPromise)
+            await bootPromise;
+    }
+    catch {
+        /* telemetry boot failure must not block the agent */
+    }
+    if (handle && typeof handle.runSpan === "function")
+        return handle.runSpan(name, attributes, fn);
+    return fn();
+}
 export async function shutdownObservability() {
     const active = handle;
     handle = undefined;
@@ -67,8 +120,13 @@ export function setObservabilityHandleForTests(next) {
     bootPromise = Promise.resolve(next);
 }
 async function emitWhenReady(fn) {
-    if (bootPromise)
-        await bootPromise;
+    try {
+        if (bootPromise)
+            await bootPromise;
+    }
+    catch {
+        return;
+    }
     if (handle)
         fn(handle);
 }

package/dist/src/observability/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/observability/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/observability/index.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/langfuse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Optional Langfuse Cloud tracing via the public ingestion API.
+ *
+ * Sentry Performance already owns the global OpenTelemetry TracerProvider
+ * (`@sentry/node` init). Langfuse is therefore a separate REST client: no
+ * second NodeSDK / TracerProvider is registered. When LANGFUSE_PUBLIC_KEY or
+ * LANGFUSE_SECRET_KEY is unset, every call is a no-op.
+ */
+import { DEFAULT_LANGFUSE_HOST } from "./config.js";
+import type { LlmGenerationInput } from "./llm.js";
+export { DEFAULT_LANGFUSE_HOST };
+export interface LangfuseConfig {
+    publicKey: string;
+    secretKey: string;
+    host: string;
+}
+export declare function readLangfuseConfig(env?: NodeJS.ProcessEnv): LangfuseConfig | undefined;
+export interface LangfuseHandle {
+    captureGeneration(input: LlmGenerationInput, options: {
+        sessionId: string;
+        userId: string;
+    }): void;
+    flush(): Promise<void>;
+}
+export declare function createLangfuseHandle(config: LangfuseConfig, options?: {
+    fetchImpl?: typeof fetch;
+}): LangfuseHandle;

package/dist/src/observability/langfuse.js

@@ -0,0 +1,65 @@
+/**
+ * Optional Langfuse Cloud tracing via the public ingestion API.
+ *
+ * Sentry Performance already owns the global OpenTelemetry TracerProvider
+ * (`@sentry/node` init). Langfuse is therefore a separate REST client: no
+ * second NodeSDK / TracerProvider is registered. When LANGFUSE_PUBLIC_KEY or
+ * LANGFUSE_SECRET_KEY is unset, every call is a no-op.
+ */
+import { PSYCLAW_VERSION } from "../branding.js";
+import { DEFAULT_LANGFUSE_HOST } from "./config.js";
+import { langfuseGenerationBody } from "./llm.js";
+export { DEFAULT_LANGFUSE_HOST };
+function trimEnv(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function readLangfuseConfig(env = process.env) {
+    const publicKey = trimEnv(env.LANGFUSE_PUBLIC_KEY);
+    const secretKey = trimEnv(env.LANGFUSE_SECRET_KEY);
+    if (!publicKey || !secretKey)
+        return undefined;
+    const host = (trimEnv(env.LANGFUSE_HOST) ?? trimEnv(env.LANGFUSE_BASE_URL) ?? DEFAULT_LANGFUSE_HOST)
+        .replace(/\/+$/, "");
+    return { publicKey, secretKey, host };
+}
+export function createLangfuseHandle(config, options = {}) {
+    const pending = new Set();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const authorization = `Basic ${Buffer.from(`${config.publicKey}:${config.secretKey}`).toString("base64")}`;
+    const enqueue = (batch) => {
+        const job = fetchImpl(`${config.host}/api/public/ingestion`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization,
+                "x-langfuse-sdk-name": "psyclaw",
+                "x-langfuse-sdk-version": PSYCLAW_VERSION,
+            },
+            body: JSON.stringify({
+                batch,
+                metadata: { batch_size: Array.isArray(batch) ? batch.length : 1, sdk_integration: "psyclaw" },
+            }),
+        }).then((response) => {
+            if (!response.ok)
+                return undefined;
+            return undefined;
+        }).catch(() => undefined).then(() => undefined);
+        pending.add(job);
+        void job.finally(() => pending.delete(job));
+    };
+    return {
+        captureGeneration(input, ids) {
+            try {
+                enqueue(langfuseGenerationBody(input, ids).ingest.batch);
+            }
+            catch {
+                /* never break the agent on telemetry */
+            }
+        },
+        async flush() {
+            await Promise.allSettled([...pending]);
+        },
+    };
+}
+//# sourceMappingURL=langfuse.js.map

package/dist/src/observability/langfuse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langfuse.js","sourceRoot":"","sources":["../../../src/observability/langfuse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAQjC,SAAS,OAAO,CAAC,KAAyB;IACxC,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACnD,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,qBAAqB,CAAC;SACjG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAOD,MAAM,UAAU,oBAAoB,CAClC,MAAsB,EACtB,UAAwC,EAAE;IAE1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,aAAa,GAAG,SAAS,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IAE3G,MAAM,OAAO,GAAG,CAAC,KAAc,EAAQ,EAAE;QACvC,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,IAAI,uBAAuB,EAAE;YAC3D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa;gBACb,qBAAqB,EAAE,SAAS;gBAChC,wBAAwB,EAAE,eAAe;aAC1C;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK;gBACL,QAAQ,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,SAAS,EAAE;aAC9F,CAAC;SACH,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;YACnB,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,OAAO,SAAS,CAAC;YACnC,OAAO,SAAS,CAAC;QACnB,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,OAAO;QACL,iBAAiB,CAAC,KAAK,EAAE,GAAG;YAC1B,IAAI,CAAC;gBACH,OAAO,CAAC,sBAAsB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3D,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;YAC1C,CAAC;QACH,CAAC;QACD,KAAK,CAAC,KAAK;YACT,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;QACzC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/observability/llm.d.ts

@@ -0,0 +1,105 @@
+/**
+ * PostHog LLM analytics + Langfuse generation payloads for the Pi stack.
+ *
+ * PsyClaw talks to models through `@earendil-works/pi-ai` / pi-coding-agent,
+ * not OpenAI/LangChain SDKs. Official PostHog guidance for that harness is
+ * either `@posthog/pi` or manual `$ai_generation` capture. We capture manually
+ * so events stay behind PsyClaw telemetry consent, share the CLI/panel
+ * distinct_id, and never include prompts, completions, or tool I/O.
+ */
+export interface LlmUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cost?: {
+        total?: number;
+    };
+}
+export interface LlmGenerationInput {
+    provider?: string;
+    model?: string;
+    usage?: LlmUsage;
+    latencyMs?: number;
+    error?: boolean;
+    errorName?: string;
+    httpStatus?: number;
+    stream?: boolean;
+    traceId?: string;
+    sessionId?: string;
+    spanName?: string;
+    surface?: string;
+}
+export type PosthogAiPropertyValue = string | number | boolean;
+export declare function usageFromUnknown(value: unknown): LlmUsage | undefined;
+/**
+ * Pull token usage out of a Pi session / RPC event without reading message
+ * content. Matches the shapes already used by the panel usage aggregator.
+ */
+export declare function extractPiGeneration(entry: unknown): LlmGenerationInput | undefined;
+export declare function lastPiGeneration(entries: readonly unknown[]): LlmGenerationInput | undefined;
+/** PostHog `$ai_generation` properties. Prompt/completion fields are omitted on purpose. */
+export declare function posthogAiGenerationProperties(input: LlmGenerationInput, options: {
+    distinctId: string;
+    sessionId: string;
+}): Record<string, PosthogAiPropertyValue>;
+export declare function langfuseGenerationBody(input: LlmGenerationInput, options: {
+    sessionId: string;
+    userId: string;
+}): {
+    traceId: string;
+    observationId: `${string}-${string}-${string}-${string}-${string}`;
+    started: string;
+    ended: string;
+    ingest: {
+        batch: ({
+            id: `${string}-${string}-${string}-${string}-${string}`;
+            timestamp: string;
+            type: string;
+            body: {
+                id: string;
+                timestamp: string;
+                name: string;
+                sessionId: string;
+                userId: string;
+                metadata: {
+                    provider: string;
+                    surface: string;
+                    privacyMode: boolean;
+                };
+            };
+        } | {
+            id: `${string}-${string}-${string}-${string}-${string}`;
+            timestamp: string;
+            type: string;
+            body: {
+                metadata: {
+                    provider: string;
+                    surface: string;
+                    privacyMode: boolean;
+                };
+                statusMessage?: string;
+                level: string;
+                costDetails?: {
+                    total: number;
+                };
+                id: `${string}-${string}-${string}-${string}-${string}`;
+                traceId: string;
+                name: string;
+                startTime: string;
+                endTime: string;
+                model: string;
+                usageDetails: {
+                    input: number;
+                    output: number;
+                    total: number;
+                    cache_read: number;
+                    cache_write: number;
+                };
+                timestamp?: never;
+                sessionId?: never;
+                userId?: never;
+            };
+        })[];
+    };
+};

package/dist/src/observability/llm.js

@@ -0,0 +1,185 @@
+/**
+ * PostHog LLM analytics + Langfuse generation payloads for the Pi stack.
+ *
+ * PsyClaw talks to models through `@earendil-works/pi-ai` / pi-coding-agent,
+ * not OpenAI/LangChain SDKs. Official PostHog guidance for that harness is
+ * either `@posthog/pi` or manual `$ai_generation` capture. We capture manually
+ * so events stay behind PsyClaw telemetry consent, share the CLI/panel
+ * distinct_id, and never include prompts, completions, or tool I/O.
+ */
+import { randomUUID } from "node:crypto";
+import { estimateUsageCost } from "../core/pricing.js";
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function usageFromUnknown(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    if (finiteNumber(record.input) === undefined
+        && finiteNumber(record.output) === undefined
+        && finiteNumber(record.cacheRead) === undefined) {
+        return undefined;
+    }
+    return record;
+}
+/**
+ * Pull token usage out of a Pi session / RPC event without reading message
+ * content. Matches the shapes already used by the panel usage aggregator.
+ */
+export function extractPiGeneration(entry) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const record = entry;
+    if (record.type === "message" && record.message && typeof record.message === "object") {
+        const message = record.message;
+        const usage = usageFromUnknown(message.usage);
+        if (!usage)
+            return undefined;
+        const provider = typeof message.provider === "string" ? message.provider : undefined;
+        const model = typeof message.responseModel === "string"
+            ? message.responseModel
+            : typeof message.model === "string"
+                ? message.model
+                : undefined;
+        const error = Boolean(message.errorMessage) || Boolean(message.error);
+        return {
+            ...(provider === undefined ? {} : { provider }),
+            ...(model === undefined ? {} : { model }),
+            usage,
+            error,
+            spanName: "pi-message",
+        };
+    }
+    if ((record.type === "agent_end" || record.type === "agent_settled") && record.message && typeof record.message === "object") {
+        return extractPiGeneration({ type: "message", message: record.message });
+    }
+    if ((record.type === "branch_summary" || record.type === "compaction") && record.usage) {
+        const usage = usageFromUnknown(record.usage);
+        if (!usage)
+            return undefined;
+        return { provider: "summaries", model: "summaries", usage, spanName: String(record.type) };
+    }
+    return undefined;
+}
+export function lastPiGeneration(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const found = extractPiGeneration(entries[index]);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/** PostHog `$ai_generation` properties. Prompt/completion fields are omitted on purpose. */
+export function posthogAiGenerationProperties(input, options) {
+    const provider = input.provider?.trim().slice(0, 80) || "unknown";
+    const model = input.model?.trim().slice(0, 120) || "unknown";
+    const usage = input.usage ?? {};
+    const inputTokens = finiteNumber(usage.input) ?? 0;
+    const outputTokens = finiteNumber(usage.output) ?? 0;
+    const cacheRead = finiteNumber(usage.cacheRead) ?? 0;
+    const cacheWrite = finiteNumber(usage.cacheWrite) ?? 0;
+    const reportedCost = finiteNumber(usage.cost?.total);
+    const estimatedCost = estimateUsageCost(usage, provider, model);
+    const latencySeconds = finiteNumber(input.latencyMs) !== undefined
+        ? Number((input.latencyMs / 1000).toFixed(4))
+        : undefined;
+    const properties = {
+        $ai_trace_id: (input.traceId ?? randomUUID()).slice(0, 80),
+        $ai_session_id: (input.sessionId ?? options.sessionId).slice(0, 80),
+        $ai_span_name: (input.spanName ?? "pi-generation").slice(0, 80),
+        $ai_model: model,
+        $ai_provider: provider,
+        $ai_input_tokens: inputTokens,
+        $ai_output_tokens: outputTokens,
+        $ai_cache_read_tokens: cacheRead,
+        $ai_cache_write_tokens: cacheWrite,
+        $ai_http_status: input.httpStatus ?? (input.error ? 500 : 200),
+        $ai_is_error: input.error === true,
+        $ai_stream: input.stream === true,
+        $ai_privacy_mode: true,
+        surface: (input.surface ?? "cli").slice(0, 32),
+        $process_person_profile: false,
+    };
+    if (latencySeconds !== undefined)
+        properties.$ai_latency = latencySeconds;
+    if (reportedCost !== undefined)
+        properties.$ai_total_cost_usd = reportedCost;
+    else if (estimatedCost > 0)
+        properties.$ai_total_cost_usd = estimatedCost;
+    if (input.errorName)
+        properties.$ai_error = input.errorName.slice(0, 80);
+    return properties;
+}
+export function langfuseGenerationBody(input, options) {
+    const provider = input.provider?.trim().slice(0, 80) || "unknown";
+    const model = input.model?.trim().slice(0, 120) || "unknown";
+    const usage = input.usage ?? {};
+    const inputTokens = finiteNumber(usage.input) ?? 0;
+    const outputTokens = finiteNumber(usage.output) ?? 0;
+    const cacheRead = finiteNumber(usage.cacheRead) ?? 0;
+    const cacheWrite = finiteNumber(usage.cacheWrite) ?? 0;
+    const started = new Date(Date.now() - (finiteNumber(input.latencyMs) ?? 0)).toISOString();
+    const ended = new Date().toISOString();
+    const traceId = input.traceId ?? randomUUID();
+    const observationId = randomUUID();
+    const reportedCost = finiteNumber(usage.cost?.total);
+    const estimatedCost = estimateUsageCost(usage, provider, model);
+    const cost = reportedCost ?? (estimatedCost > 0 ? estimatedCost : undefined);
+    return {
+        traceId,
+        observationId,
+        started,
+        ended,
+        ingest: {
+            batch: [
+                {
+                    id: randomUUID(),
+                    timestamp: ended,
+                    type: "trace-create",
+                    body: {
+                        id: traceId,
+                        timestamp: started,
+                        name: input.spanName ?? "pi-generation",
+                        sessionId: options.sessionId,
+                        userId: options.userId,
+                        metadata: {
+                            provider,
+                            surface: input.surface ?? "cli",
+                            privacyMode: true,
+                        },
+                    },
+                },
+                {
+                    id: randomUUID(),
+                    timestamp: ended,
+                    type: "generation-create",
+                    body: {
+                        id: observationId,
+                        traceId,
+                        name: input.spanName ?? "pi-generation",
+                        startTime: started,
+                        endTime: ended,
+                        model,
+                        usageDetails: {
+                            input: inputTokens,
+                            output: outputTokens,
+                            total: inputTokens + outputTokens + cacheRead + cacheWrite,
+                            cache_read: cacheRead,
+                            cache_write: cacheWrite,
+                        },
+                        ...(cost === undefined ? {} : { costDetails: { total: cost } }),
+                        level: input.error ? "ERROR" : "DEFAULT",
+                        ...(input.errorName === undefined ? {} : { statusMessage: input.errorName.slice(0, 200) }),
+                        metadata: {
+                            provider,
+                            surface: input.surface ?? "cli",
+                            privacyMode: true,
+                        },
+                    },
+                },
+            ],
+        },
+    };
+}
+//# sourceMappingURL=llm.js.map

package/dist/src/observability/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/observability/llm.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/node-sdks.d.ts

@@ -1,11 +1,20 @@
 /**
  * Loaded only after telemetry is confirmed enabled. Importing this file will
  * pull in Sentry/PostHog; callers must keep that behind the preference gate.
+ *
+ * Init order (documented in docs/telemetry.md):
+ * 1. Sentry.init — owns the global OpenTelemetry TracerProvider for Performance.
+ * 2. PostHog Node client — product events + `$ai_generation`.
+ * 3. Langfuse REST ingestion — optional, isolated from OTel (no second TracerProvider).
  */
 import type { AgentEventPropertyValue, NodeObservabilityConfig } from "./config.js";
+import { type LlmGenerationInput } from "./llm.js";
 export interface ObservabilityHandle {
+    readonly distinctId?: string;
     captureEvent(name: string, properties: Record<string, AgentEventPropertyValue>): void;
     captureError(error: unknown, context?: Record<string, string>): void;
+    captureLlmGeneration?(input: LlmGenerationInput): void;
+    runSpan?<T>(name: string, attributes: Record<string, string>, fn: () => Promise<T>): Promise<T>;
     flush(): Promise<void>;
 }
 export declare function bootNodeSdks(config: NodeObservabilityConfig): Promise<ObservabilityHandle>;