@agent-native/core 0.172.2 → 0.172.4

package/dist/observability/posthog-ai.d.ts

@@ -24,10 +24,10 @@
  * schema, and a name it does not define today it may define tomorrow with
  * different meaning — `input_truncated` / `spans_dropped` cannot collide.
  *
- * Content (`$ai_input` / `$ai_output_choices` / `$ai_input_state` /
- * `$ai_output_state`) is gated on config and always OMITTED when disabled.
- * Sending `[]` instead would be indistinguishable from a run that genuinely had
- * no messages.
+ * Content (a generation's `$ai_input` / `$ai_output_choices`, a span's
+ * `$ai_input_state` / `$ai_output_state`) is gated on config and always OMITTED
+ * when disabled. Sending `[]` instead would be indistinguishable from a run
+ * that genuinely had no messages.
  *
  * @see https://posthog.com/docs/ai-observability/traces
  * @see https://posthog.com/docs/ai-observability/spans
@@ -42,12 +42,18 @@ export interface AiErrorDetail {
     terminal_state?: string;
     retryable?: boolean;
 }
+export declare function resolveAiError(isError: boolean, error: AiErrorDetail | undefined): AiErrorDetail | undefined;
 /**
  * Serialize a content value under a byte ceiling.
  *
- * Returns `{ truncated: true }` with a placeholder rather than a silently
- * shortened payload — a trace that shows half a conversation as if it were the
- * whole one is worse than one that says it was cut.
+ * A message list keeps the last user message behind a marker entry naming what
+ * was dropped — what was asked is what a trace is opened for, and it stays
+ * small. Replacing the whole conversation with a placeholder, which is what
+ * this did, left nothing at all.
+ *
+ * Anything else (a string, an object) still becomes a placeholder: there is no
+ * message to keep. Either way `truncated` is true, so a cut payload can never
+ * be read as a complete one.
  */
 export declare function boundAiContent(value: unknown): {
     value: unknown;
@@ -66,6 +72,10 @@ export interface AiTraceEventInput {
     durationMs: number;
     isError: boolean;
     error?: AiErrorDetail;
+    /** What KIND of failure this was — a terminal code, a cut-off reason, an
+     *  engine error code. A classification, never content, so it ships even when
+     *  the message is withheld. */
+    errorType?: string;
     inputTokens?: number;
     outputTokens?: number;
     costUsd?: number;
@@ -73,11 +83,15 @@ export interface AiTraceEventInput {
     /** Browser session id, when the run originated from a page. Links the trace
      *  to PostHog session replay. */
     browserSessionId?: string;
-    /** Omitted unless `capturePrompts` is on. */
-    inputState?: unknown;
-    outputState?: unknown;
     extraProperties?: Record<string, unknown>;
 }
+/**
+ * The run's prompt and answer are NOT carried here. Every round-trip emits a
+ * generation with its own `$ai_input` / `$ai_output_choices`, so a trace-level
+ * copy repeated the first call's prompt and the last call's answer on a second
+ * event. The trace owns what only it knows: the run's name, failure, metadata
+ * and totals.
+ */
 export declare function emitAiTraceEvent(input: AiTraceEventInput): void;
 export interface AiSpanEventInput {
     runId: string;
@@ -90,6 +104,9 @@ export interface AiSpanEventInput {
     latencySeconds: number;
     isError: boolean;
     error?: AiErrorDetail;
+    /** The tool failure's class — `tool_error`, `interrupted`. A classification,
+     *  never the tool's output, so it ships with `captureToolResults` off. */
+    errorType?: string;
     createdAt: number;
     browserSessionId?: string;
     /** Omitted unless `captureToolArgs` / `captureToolResults` are on. */
@@ -103,8 +120,12 @@ export interface AiFeedbackSurveyInput {
     threadId: string | null;
     userId: string | null;
     feedbackType: "thumbs_up" | "thumbs_down" | "category" | "text";
-    /** The submitted value: sentiment label, chosen category, or free text. */
+    /** The submitted value: chosen category or free text. Ignored for thumbs,
+     *  which answer a rating question and travel as PostHog's choice index. */
     value: string;
+    /** Groups the events of one response. A thumbs-down and the follow-up text
+     *  it opens are two `survey sent` events answering two questions of the SAME
+     *  response, so they must share this id. */
     submissionId: string;
     model?: string;
     browserSessionId?: string;
@@ -117,6 +138,10 @@ export interface AiFeedbackSurveyInput {
  * nowhere. Returns `false` and emits nothing when no survey id is configured:
  * inventing one would produce events attached to a survey that does not exist.
  *
+ * A thumbs vote answers the survey's first question; a category or free-text
+ * answer answers the follow-up question after it. Both share the caller's
+ * `submissionId`, which is how PostHog joins them into one response.
+ *
  * Sent to PostHog ONLY, not through `track()`. The survey response carries the
  * user's free-text feedback verbatim, and configuring a PostHog survey id must
  * not silently start shipping that text to Mixpanel, Amplitude, webhooks, or

package/dist/observability/posthog-ai.js

@@ -24,10 +24,10 @@
  * schema, and a name it does not define today it may define tomorrow with
  * different meaning — `input_truncated` / `spans_dropped` cannot collide.
  *
- * Content (`$ai_input` / `$ai_output_choices` / `$ai_input_state` /
- * `$ai_output_state`) is gated on config and always OMITTED when disabled.
- * Sending `[]` instead would be indistinguishable from a run that genuinely had
- * no messages.
+ * Content (a generation's `$ai_input` / `$ai_output_choices`, a span's
+ * `$ai_input_state` / `$ai_output_state`) is gated on config and always OMITTED
+ * when disabled. Sending `[]` instead would be indistinguishable from a run
+ * that genuinely had no messages.
  *
  * @see https://posthog.com/docs/ai-observability/traces
  * @see https://posthog.com/docs/ai-observability/spans
@@ -38,6 +38,21 @@ import { boundedText } from "../tracking/redaction.js";
 export const MAX_AI_CONTENT_BYTES = 128 * 1024;
 /** Hard ceiling on emitted `$ai_span` events per run. */
 export const MAX_AI_SPANS_PER_RUN = 100;
+/**
+ * `$ai_is_error: true` with no `$ai_error` is a dead end: the reader learns
+ * something broke and nothing else, which is how a failed tool span reached
+ * PostHog saying only "error". Emitters fall back to this rather than shipping
+ * the flag alone — a layer that failed without reporting a message is itself
+ * worth seeing, and is not the same as a message we chose to withhold.
+ */
+const UNREPORTED_ERROR = {
+    message: "failed without a reported error message",
+};
+export function resolveAiError(isError, error) {
+    if (!isError)
+        return undefined;
+    return error ?? UNREPORTED_ERROR;
+}
 function trackAiEvent(name, properties, userId, occurredAt) {
     for (const key of Object.keys(properties)) {
         if (properties[key] === undefined)
@@ -55,12 +70,24 @@ function trackAiEvent(name, properties, userId, occurredAt) {
         // Tracking must never affect the agent run or trace persistence.
     }
 }
+function utf8Bytes(text) {
+    return typeof Buffer !== "undefined"
+        ? Buffer.byteLength(text, "utf8")
+        : new TextEncoder().encode(text).length;
+}
+/** Room reserved for the marker entry that reports what was dropped. */
+const OMISSION_MARKER_BYTES = 512;
 /**
  * Serialize a content value under a byte ceiling.
  *
- * Returns `{ truncated: true }` with a placeholder rather than a silently
- * shortened payload — a trace that shows half a conversation as if it were the
- * whole one is worse than one that says it was cut.
+ * A message list keeps the last user message behind a marker entry naming what
+ * was dropped — what was asked is what a trace is opened for, and it stays
+ * small. Replacing the whole conversation with a placeholder, which is what
+ * this did, left nothing at all.
+ *
+ * Anything else (a string, an object) still becomes a placeholder: there is no
+ * message to keep. Either way `truncated` is true, so a cut payload can never
+ * be read as a complete one.
  */
 export function boundAiContent(value) {
     let serialized;
@@ -72,23 +99,45 @@ export function boundAiContent(value) {
     }
     if (serialized === undefined)
         return { value: undefined, truncated: false };
-    const bytes = typeof Buffer !== "undefined"
-        ? Buffer.byteLength(serialized, "utf8")
-        : new TextEncoder().encode(serialized).length;
+    const bytes = utf8Bytes(serialized);
     if (bytes <= MAX_AI_CONTENT_BYTES)
         return { value, truncated: false };
+    if (Array.isArray(value)) {
+        // What was ASKED is the one thing worth rescuing from an oversized
+        // transcript: the rest is context the thread itself still holds, and
+        // keeping as much of it as fits just ships the ceiling on every event.
+        const lastUser = value.findLast((entry) => !!entry &&
+            typeof entry === "object" &&
+            entry.role === "user");
+        const kept = lastUser !== undefined &&
+            utf8Bytes(JSON.stringify(lastUser) ?? "null") <=
+                MAX_AI_CONTENT_BYTES - OMISSION_MARKER_BYTES
+            ? [lastUser]
+            : [];
+        return {
+            value: [
+                {
+                    role: "system",
+                    content: `[${value.length - kept.length} message(s) omitted: ${bytes} bytes exceeded the ${MAX_AI_CONTENT_BYTES}-byte trace content limit]`,
+                },
+                ...kept,
+            ],
+            truncated: true,
+        };
+    }
     return {
         value: `[truncated: ${bytes} bytes exceeded the ${MAX_AI_CONTENT_BYTES}-byte trace content limit]`,
         truncated: true,
     };
 }
+/**
+ * The run's prompt and answer are NOT carried here. Every round-trip emits a
+ * generation with its own `$ai_input` / `$ai_output_choices`, so a trace-level
+ * copy repeated the first call's prompt and the last call's answer on a second
+ * event. The trace owns what only it knows: the run's name, failure, metadata
+ * and totals.
+ */
 export function emitAiTraceEvent(input) {
-    const inputContent = input.inputState === undefined
-        ? undefined
-        : boundAiContent(input.inputState);
-    const outputContent = input.outputState === undefined
-        ? undefined
-        : boundAiContent(input.outputState);
     trackAiEvent("$ai_trace", {
         ...input.extraProperties,
         $ai_trace_id: input.runId,
@@ -97,15 +146,14 @@ export function emitAiTraceEvent(input) {
         $ai_model: input.model,
         $ai_provider: input.provider,
         $ai_is_error: input.isError,
-        $ai_error: input.error,
+        $ai_error: resolveAiError(input.isError, input.error),
+        $ai_error_type: input.isError
+            ? (input.errorType ?? "run_error")
+            : undefined,
         duration_ms: Math.round(input.durationMs),
         input_tokens: input.inputTokens,
         output_tokens: input.outputTokens,
         cost_usd: input.costUsd,
-        $ai_input_state: inputContent?.value,
-        $ai_output_state: outputContent?.value,
-        input_truncated: inputContent?.truncated || undefined,
-        output_truncated: outputContent?.truncated || undefined,
         $session_id: input.browserSessionId,
         created_at: new Date(input.createdAt).toISOString(),
     }, input.userId, input.createdAt);
@@ -126,7 +174,10 @@ export function emitAiSpanEvent(input) {
         $ai_span_name: input.spanName,
         $ai_latency: input.latencySeconds,
         $ai_is_error: input.isError,
-        $ai_error: input.error,
+        $ai_error: resolveAiError(input.isError, input.error),
+        $ai_error_type: input.isError
+            ? (input.errorType ?? "tool_error")
+            : undefined,
         $ai_input_state: inputContent?.value,
         $ai_output_state: outputContent?.value,
         input_truncated: inputContent?.truncated || undefined,
@@ -135,6 +186,14 @@ export function emitAiSpanEvent(input) {
         created_at: new Date(input.createdAt).toISOString(),
     }, input.userId, input.createdAt);
 }
+/**
+ * PostHog's thumbs survey is a choice question, and the response is the
+ * choice's 1-based index — not a label. Sending "thumbs_up" put a string where
+ * the rating belongs, so the vote counted as an unrecognized answer.
+ *
+ * @see https://posthog.com/docs/ai-observability/user-feedback/manual-event-capture
+ */
+const THUMB_RESPONSE_INDEX = { thumbs_up: 1, thumbs_down: 2 };
 /**
  * Emit PostHog's documented manual feedback event for an LLM trace.
  *
@@ -143,6 +202,10 @@ export function emitAiSpanEvent(input) {
  * nowhere. Returns `false` and emits nothing when no survey id is configured:
  * inventing one would produce events attached to a survey that does not exist.
  *
+ * A thumbs vote answers the survey's first question; a category or free-text
+ * answer answers the follow-up question after it. Both share the caller's
+ * `submissionId`, which is how PostHog joins them into one response.
+ *
  * Sent to PostHog ONLY, not through `track()`. The survey response carries the
  * user's free-text feedback verbatim, and configuring a PostHog survey id must
  * not silently start shipping that text to Mixpanel, Amplitude, webhooks, or
@@ -155,17 +218,23 @@ export function emitAiFeedbackSurveyEvent(input) {
     const surveyId = process.env.POSTHOG_AI_FEEDBACK_SURVEY_ID?.trim();
     if (!surveyId)
         return false;
-    const questionId = process.env.POSTHOG_AI_FEEDBACK_SURVEY_QUESTION_ID?.trim();
-    // PostHog accepts `$survey_response` for a single-question survey and
-    // `$survey_response_<questionId>` when the survey has named questions.
-    const responseKey = questionId
-        ? `$survey_response_${questionId}`
-        : "$survey_response";
+    const thumbResponse = input.feedbackType === "thumbs_up" || input.feedbackType === "thumbs_down"
+        ? THUMB_RESPONSE_INDEX[input.feedbackType]
+        : undefined;
+    // `$survey_response` is the survey's first question — the thumbs — and
+    // `$survey_response_1` the follow-up asked after a thumbs-down. Putting the
+    // free text on the first key instead would file prose where the rating
+    // belongs and skew every thumbs metric in the survey.
+    const responses = thumbResponse !== undefined
+        ? { $survey_response: thumbResponse }
+        : { $survey_response_1: input.value };
     const properties = {
         $survey_id: surveyId,
-        [responseKey]: input.value,
+        ...responses,
         $survey_submission_id: input.submissionId,
-        $survey_completed: true,
+        // A thumbs-down opens the follow-up question, so the response is not
+        // complete until that answer arrives (or the user closes it without one).
+        $survey_completed: input.feedbackType !== "thumbs_down",
         $ai_trace_id: input.runId ?? undefined,
         $ai_session_id: input.threadId ?? undefined,
         $ai_model: input.model,

package/dist/observability/routes.js

@@ -216,8 +216,15 @@ export function createObservabilityHandler() {
                     threadId,
                     userId: owner,
                     feedbackType,
-                    value: isThumb ? feedbackType : value,
-                    submissionId: id,
+                    value,
+                    // One PostHog response per rated message, not per row: a thumbs-down
+                    // and the free text it opens are two answers to the same survey, and
+                    // a fresh id per row would file them as two unrelated responses.
+                    // Falls back to the row id when there is no message to key on, which
+                    // groups nothing — the honest outcome when nothing can be grouped.
+                    submissionId: runId && typeof body.messageSeq === "number"
+                        ? `${runId}:${body.messageSeq}`
+                        : id,
                     model,
                     browserSessionId: getRequestContext()?.browserSessionId,
                 });