@teaflask/assistant 0.9.0 → 0.10.0

package/dist/components/teaflask-assistant-provider.d.ts

@@ -86,9 +86,10 @@ export interface TeaflaskAssistantProviderBaseProps {
      */
     onError?: (error: Error) => void;
     /**
-     * Called with product analytics events (approval submits and stream
-     * failures) that you can forward to your own analytics. If it throws, the
-     * error goes to `onError`.
+     * Called with product analytics events (approval submits, stream failures
+     * and failed replies) that you can forward to your own analytics. If it
+     * throws, the error goes to `onError`. Without it, each failed reply writes
+     * one console warning with its reason code instead.
      */
     onTelemetry?: (event: AssistantTelemetryEvent) => void;
     /**

package/dist/contract/telemetry.d.ts

@@ -1,3 +1,5 @@
+export type { FailureReasonCode } from "../generated/models/index.js";
+import type { FailureReasonCode } from "../generated/models/index.js";
 /**
  * Why clicking approve or deny sent nothing. "no_active_thread" means no
  * conversation was open; "card_missing" means the request was no longer shown;
@@ -64,12 +66,31 @@ export interface StreamFailedTelemetryEvent {
         last_committed_sse_id: string | null;
     };
 }
+/**
+ * Reported to onTelemetry when a reply fails while the user is watching. The
+ * user sees one general sentence, so this event's reason_code is how your page
+ * learns why; log it and never show it. Failures replayed when a conversation
+ * reopens are not reported again.
+ */
+export interface TurnFailedTelemetryEvent {
+    /** Always "turn_failed". */
+    name: "turn_failed";
+    /**
+     * The conversation's thread_id, the failed reply's turn_id, and its
+     * reason_code, the same code the stream's turn_failed event carries as
+     * reasonCode.
+     */
+    properties: {
+        thread_id: string;
+        turn_id: string;
+        reason_code: FailureReasonCode;
+    };
+}
 /**
  * Any event passed to the provider's onTelemetry callback, for forwarding to
  * your own analytics. None carry message text, tool arguments or prompts.
  */
-export type AssistantTelemetryEvent = ApprovalSubmitTelemetryEvent | StreamFailedTelemetryEvent;
+export type AssistantTelemetryEvent = ApprovalSubmitTelemetryEvent | StreamFailedTelemetryEvent | TurnFailedTelemetryEvent;
 export declare function streamFailureClassOf(error: Error, context: {
     sawBodyBytes: boolean;
 }): StreamFailureClass;
-export {};

package/dist/core/assistant-session-registry.js

@@ -167,6 +167,7 @@ class SessionEntry {
                 this._reportToEveryRegistrant(error);
             },
             onTelemetry: (event) => {
+                this._warnOfAFailureNoHostLogs(event);
                 for (const registration of [...this.registrations]) {
                     try {
                         registration.registrant.onTelemetry?.(event);
@@ -230,6 +231,15 @@ class SessionEntry {
         }
         return merged;
     }
+    _warnOfAFailureNoHostLogs(event) {
+        if (event.name !== "turn_failed" || this._someRegistrantLogsTelemetry()) {
+            return;
+        }
+        console.warn("[teaflask] reply failed:", event.properties.reason_code, event.properties.turn_id);
+    }
+    _someRegistrantLogsTelemetry() {
+        return [...this.registrations].some((registration) => registration.registrant.onTelemetry !== null);
+    }
     _reportToEveryRegistrant(error) {
         for (const registration of [...this.registrations]) {
             try {

package/dist/core/connection-epoch.d.ts

@@ -1,4 +1,5 @@
 import type { Message } from "@ag-ui/core";
+import type { AssistantTelemetryEvent } from "../contract/telemetry.js";
 import { ServingReplayStreamAgent } from "../transport/replay-stream-agent.js";
 import { type StreamResumeStore } from "../transport/stream-resume.js";
 import type { TokenSession } from "../transport/token-session.js";
@@ -109,6 +110,8 @@ export interface ConnectionEpochDeps {
     onRunSettled: () => void;
     onQuietClose: (stillStreaming: () => boolean) => void;
     onWorkflowRestarted: () => void;
+    onTelemetry: (event: AssistantTelemetryEvent) => void;
+    settledFailedTurnId: string | null;
 }
 export interface ConnectionEpoch {
     epochId: number;

package/dist/core/connection-epoch.js

@@ -15,7 +15,7 @@ import { toolErrorRecorder, wellFormedToolErrorAnchorsOf, } from "./tool-error-a
 import { toolDecisionRecorder, wellFormedToolDecisionAnchorsOf, } from "./tool-decision-anchors.js";
 import { toolDenialRecorder, wellFormedToolDenialAnchorsOf, } from "./tool-denial-anchors.js";
 import { toolRefusalRecorder, wellFormedToolRefusalAnchorsOf, } from "./tool-refusal-anchors.js";
-import { turnFailedMarkerRecorder, wellFormedFailAnchorsOf, } from "./turn-failed-anchors.js";
+import { failedTurnRecorder, turnFailedMarkerRecorder, wellFormedFailAnchorsOf, } from "./turn-failed-anchors.js";
 import { turnUsageRecorder, wellFormedTurnUsageAnchorsOf, } from "./turn-usage-anchors.js";
 import { messagesRecorder, streamErrorRecorder } from "./messages-cell.js";
 import { withdrawnReplyRecorder, withoutWithdrawnReplies, } from "./withdrawn-anchors.js";
@@ -110,6 +110,19 @@ function _runMarkerSubscriptionsOf(agent, deps) {
                 deps.publishMarkerAnchors();
             }
         })),
+        agent.subscribe(failedTurnRecorder((failed) => {
+            if (!_isNewsToTheHost(failed, deps)) {
+                return;
+            }
+            deps.onTelemetry({
+                name: "turn_failed",
+                properties: {
+                    thread_id: deps.threadId,
+                    turn_id: failed.turnId,
+                    reason_code: failed.reasonCode,
+                },
+            });
+        })),
         agent.subscribe(subagentDeliveryMarkerRecorder((deliveryRunId, messageId, results) => {
             if (deps.resume.recordSubagentDelivery(deliveryRunId, messageId, results)) {
                 deps.publishMarkerAnchors();
@@ -124,6 +137,10 @@ function _runMarkerSubscriptionsOf(agent, deps) {
         })),
     ];
 }
+function _isNewsToTheHost(failed, deps) {
+    return (failed.turnId !== deps.settledFailedTurnId &&
+        deps.resume.recordFailedTurnReported(failed.turnId));
+}
 function _visibleAnchorOf(messageId, agent, deps) {
     const visible = _visibleMessagesOf(agent, deps);
     if (visible.some((message) => message.id === messageId)) {

package/dist/core/conversation-adoption.js

@@ -117,6 +117,7 @@ function _finishAdoption(store, detail) {
         resume,
         approvalInbox,
         coworkerRequestTurns: detail.turns,
+        settledFailedTurnId: _settledFailedTurnIdOf(detail.turns),
     };
     if (!continuing) {
         store.questionDrafts.clearAll();
@@ -152,6 +153,10 @@ function adoptCoworkerRequests(store, turns) {
         publishApprovalCards(store, active.approvalInbox.cards());
     }
 }
+function _settledFailedTurnIdOf(turns) {
+    const newest = turns.at(-1);
+    return newest?.status === "failed" ? newest.id : null;
+}
 export function adoptRefreshedDetail(store, detail) {
     const active = store._active;
     if (active?.thread.id !== detail.thread.id) {
@@ -168,6 +173,7 @@ export function adoptRefreshedDetail(store, detail) {
             resume: active.resume,
             approvalInbox: active.approvalInbox,
             coworkerRequestTurns: active.coworkerRequestTurns,
+            settledFailedTurnId: active.settledFailedTurnId,
         };
     }
     _adoptWireModelPick(store, detail.thread, { evenWhenDirty: false });
@@ -217,6 +223,7 @@ export function enterConversationFromSend(store, thread, turn, sentPick) {
         resume,
         approvalInbox,
         coworkerRequestTurns: [],
+        settledFailedTurnId: null,
     };
     if (sameModelPick(store._modelPick, sentPick)) {
         _adoptWireModelPick(store, thread, { evenWhenDirty: true });

package/dist/core/conversation-contract.d.ts

@@ -17,6 +17,7 @@ export interface ActiveConversation {
     resume: StreamResumeStore;
     approvalInbox: ApprovalInbox;
     coworkerRequestTurns: readonly ServingAssistantTurn[];
+    settledFailedTurnId: string | null;
 }
 /**
  * State and controls for writing and sending messages in the open conversation,

package/dist/core/epoch-sync.js

@@ -89,6 +89,8 @@ function _mintEpochDeps(store, active, epochId) {
         onRunSettled: store.handleRunSettled,
         onQuietClose: store.handleStreamClosedQuietly,
         onWorkflowRestarted: store.handleWorkflowRestarted,
+        onTelemetry: store.deps.onTelemetry,
+        settledFailedTurnId: active.settledFailedTurnId,
     };
 }
 export function retireEpoch(store) {

package/dist/core/turn-failed-anchors.d.ts

@@ -1,4 +1,5 @@
 import { receiptOf, wellFormedReceiptAnchorsOf, withReceiptAnchored, type AnchoredReceipts } from "./receipt-anchors.js";
+import { FailureReasonCode } from "../generated/models/index.js";
 import type { AgentSubscriber } from "@ag-ui/client";
 /**
  * The failure sentences for a failed turn, split by whether they are shown
@@ -10,3 +11,9 @@ export declare const turnFailedReceiptOf: typeof receiptOf;
 export declare const withTurnFailedAnchored: typeof withReceiptAnchored;
 export declare const wellFormedFailAnchorsOf: typeof wellFormedReceiptAnchorsOf;
 export declare function turnFailedMarkerRecorder(onReceiptAnchored: (failedRunId: string, messageId: string, position: keyof AnchoredTurnFailReceipts, receipts: string[]) => void): AgentSubscriber;
+export interface FailedTurn {
+    turnId: string;
+    reasonCode: FailureReasonCode;
+}
+export declare function failedTurnOf(value: unknown): FailedTurn | null;
+export declare function failedTurnRecorder(onFailedLive: (failed: FailedTurn) => void): AgentSubscriber;

package/dist/core/turn-failed-anchors.js

@@ -1,5 +1,6 @@
 import { receiptMarkerRecorder, receiptOf, wellFormedReceiptAnchorsOf, withReceiptAnchored, } from "./receipt-anchors.js";
 import { TURN_FAILED_EVENT_NAME } from "../contract/events.js";
+import { FailureReasonCode, } from "../generated/models/index.js";
 export const EMPTY_TURN_FAILED_ANCHORS = new Map();
 export const turnFailedReceiptOf = receiptOf;
 export const withTurnFailedAnchored = withReceiptAnchored;
@@ -7,3 +8,44 @@ export const wellFormedFailAnchorsOf = wellFormedReceiptAnchorsOf;
 export function turnFailedMarkerRecorder(onReceiptAnchored) {
     return receiptMarkerRecorder(TURN_FAILED_EVENT_NAME, onReceiptAnchored);
 }
+export function failedTurnOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const payload = value;
+    if (typeof payload.turnId !== "string" || payload.turnId === "") {
+        return null;
+    }
+    return {
+        turnId: payload.turnId,
+        reasonCode: _knownCodeOf(payload.reasonCode),
+    };
+}
+function _knownCodeOf(code) {
+    const known = Object.values(FailureReasonCode);
+    return known.includes(code)
+        ? code
+        : FailureReasonCode.internal_error;
+}
+export function failedTurnRecorder(onFailedLive) {
+    let pending = null;
+    return {
+        onRunInitialized() {
+            pending = null;
+        },
+        onCustomEvent({ event }) {
+            if (event.name === TURN_FAILED_EVENT_NAME) {
+                pending = failedTurnOf(event.value);
+            }
+        },
+        onRunFinishedEvent() {
+            pending = null;
+        },
+        onRunErrorEvent() {
+            if (pending !== null) {
+                onFailedLive(pending);
+            }
+            pending = null;
+        },
+    };
+}

package/dist/generated/models/failureReasonCode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Why a reply failed, coarse on purpose since it is visible in the browser.
+ * "model_unavailable": the AI model did not respond; "rate_limited": too many
+ * requests right now; "credential_declined": an API key or connected ChatGPT
+ * plan was refused; "out_of_credit": your Teaflask organization has no funds to
+ * pay for replies; "too_long": the message or conversation is too long;
+ * "content_refused": the model's content policy refused the message;
+ * "configuration_error": the assistant's setup asks for something its model
+ * cannot do; "internal_error": anything else. Treat an unknown code as
+ * "internal_error".
+ */
+export type FailureReasonCode = (typeof FailureReasonCode)[keyof typeof FailureReasonCode];
+/**
+ * Why a reply failed, coarse on purpose since it is visible in the browser.
+ * "model_unavailable": the AI model did not respond; "rate_limited": too many
+ * requests right now; "credential_declined": an API key or connected ChatGPT
+ * plan was refused; "out_of_credit": your Teaflask organization has no funds to
+ * pay for replies; "too_long": the message or conversation is too long;
+ * "content_refused": the model's content policy refused the message;
+ * "configuration_error": the assistant's setup asks for something its model
+ * cannot do; "internal_error": anything else. Treat an unknown code as
+ * "internal_error".
+ */
+export declare const FailureReasonCode: {
+    readonly model_unavailable: "model_unavailable";
+    readonly rate_limited: "rate_limited";
+    readonly credential_declined: "credential_declined";
+    readonly out_of_credit: "out_of_credit";
+    readonly too_long: "too_long";
+    readonly content_refused: "content_refused";
+    readonly configuration_error: "configuration_error";
+    readonly internal_error: "internal_error";
+};

package/dist/generated/models/failureReasonCode.js

@@ -0,0 +1,10 @@
+export const FailureReasonCode = {
+    model_unavailable: "model_unavailable",
+    rate_limited: "rate_limited",
+    credential_declined: "credential_declined",
+    out_of_credit: "out_of_credit",
+    too_long: "too_long",
+    content_refused: "content_refused",
+    configuration_error: "configuration_error",
+    internal_error: "internal_error",
+};

package/dist/generated/models/index.d.ts

@@ -45,6 +45,7 @@ export * from "./errorEnvelope.js";
 export * from "./evidenceAfterVoidRecordedMarker.js";
 export * from "./evidenceAfterVoidRecordedMarkerError.js";
 export * from "./evidenceAfterVoidRecordedMarkerResult.js";
+export * from "./failureReasonCode.js";
 export * from "./fileSource.js";
 export * from "./functionCall.js";
 export * from "./getServingAssistantThreadParams.js";

package/dist/generated/models/index.js

@@ -45,6 +45,7 @@ export * from "./errorEnvelope.js";
 export * from "./evidenceAfterVoidRecordedMarker.js";
 export * from "./evidenceAfterVoidRecordedMarkerError.js";
 export * from "./evidenceAfterVoidRecordedMarkerResult.js";
+export * from "./failureReasonCode.js";
 export * from "./fileSource.js";
 export * from "./functionCall.js";
 export * from "./getServingAssistantThreadParams.js";

package/dist/generated/models/turnFailedMarker.d.ts

@@ -1,3 +1,6 @@
+import type { FailureReasonCode } from "./failureReasonCode.js";
 export interface TurnFailedMarker {
     receipt: string;
+    reasonCode?: FailureReasonCode;
+    turnId?: string | null;
 }

package/dist/headless.d.ts

@@ -1,7 +1,7 @@
 export { TeaflaskAssistantProvider, type TeaflaskAssistantAnonymousProps, type TeaflaskAssistantIdentityProps, type TeaflaskAssistantProviderBaseProps, type TeaflaskAssistantProviderProps, } from "./components/teaflask-assistant-provider.js";
 export type { AssistantTheme, AssistantThemeDarkTokens, AssistantThemeMode, AssistantThemeTokens, } from "./appearance/theme.js";
 export type { ActionsAdapter, ActionIntent, ActionIntentAction, ActionIntentGraphQL, CookiesActionsAdapter, HeadersActionsAdapter, RequestActionsAdapter, } from "./contract/actions-adapter.js";
-export type { ApprovalSubmitTelemetryEvent, AssistantTelemetryEvent, StreamFailedTelemetryEvent, } from "./contract/telemetry.js";
+export type { ApprovalSubmitTelemetryEvent, AssistantTelemetryEvent, StreamFailedTelemetryEvent, TurnFailedTelemetryEvent, } from "./contract/telemetry.js";
 export type { AssistantSuggestion, AssistantSuggestionInput, AssistantSuggestionKind, } from "./components/conversation-view.js";
 export type { IconAdapter, JsonSchema, ToolViewAdapter, ToolViewCall, ToolViewInstance, ToolViewProps, ToolViewRegistration, ToolViewRegistry, } from "./core/tool-view.js";
 export { useAssistantConversation, type AssistantConversation, type OpenConversation, } from "./components/use-assistant-conversation.js";

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { ServingErrorCode, ServingErrorCodeOnTheWire, } from "./contract/er
 export type { ServingAssistantThread, TurnStatus } from "./contract/threads.js";
 export { activeFoldElapsedOf, settledFoldDurationOf, type BlockTiming, type SegmentDuration, } from "./core/segment-timing.js";
 export type { MemoryUpdated } from "./core/memory-provenance-anchors.js";
-export type { ApprovalSubmitDropReason, ApprovalSubmitTelemetryEvent, AssistantTelemetryEvent, StreamFailedTelemetryEvent, StreamFailureClass, } from "./contract/telemetry.js";
+export type { ApprovalSubmitDropReason, ApprovalSubmitTelemetryEvent, AssistantTelemetryEvent, FailureReasonCode, StreamFailedTelemetryEvent, StreamFailureClass, TurnFailedTelemetryEvent, } from "./contract/telemetry.js";
 export type { ToolCallDisplay, ToolCallState, ToolCallViewModel, } from "./core/tool-call-display.js";
 export { TOOL_CALL_ICONS, toolCallPresentationOf, type ToolCallIcon, type ToolCallPresentation, } from "./core/tool-call-presentation.js";
 export { actionToolName, actionToolViews, resolvedToolViewsOf, type IconAdapter, type JsonSchema, type ResolvedToolView, type ResolvedToolViewIcon, type ToolViewAdapter, type ToolViewCall, type ToolViewInstance, type ToolViewProps, type ToolViewRegistration, type ToolViewRegistry, type ToolViewResolution, type ToolViewThemeMode, } from "./core/tool-view.js";

package/dist/transport/stream-resume.d.ts

@@ -36,8 +36,10 @@ export declare class StreamResumeStore {
     private readonly anchoredResumptions;
     private readonly anchoredFailedRuns;
     private readonly anchoredDeliveryRuns;
+    private readonly reportedFailedTurns;
     recordResumeAnchor(runId: string | null, messageId: string, markerValue: unknown, markerTimestamp: number | null): boolean;
     recordTurnFailedReceipts(failedRunId: string, messageId: string, position: keyof AnchoredTurnFailReceipts, receipts: string[]): boolean;
+    recordFailedTurnReported(turnId: string): boolean;
     recordSubagentDelivery(deliveryRunId: string, messageId: string, results: DeliveredResult[]): boolean;
     recordToolError(toolCallId: string, errorText: string): void;
     recordToolRefusal(toolCallId: string, sentence: string): void;

package/dist/transport/stream-resume.js

@@ -37,6 +37,7 @@ export class StreamResumeStore {
     anchoredResumptions = new Set();
     anchoredFailedRuns = new Set();
     anchoredDeliveryRuns = new Set();
+    reportedFailedTurns = new Set();
     recordResumeAnchor(runId, messageId, markerValue, markerTimestamp) {
         const attempt = _wireCounterOf(markerValue, "attempt");
         const carriesRound = typeof markerValue === "object" &&
@@ -60,6 +61,13 @@ export class StreamResumeStore {
         this.turnFailedAnchors = withTurnFailedAnchored(this.turnFailedAnchors, messageId, position, receipts);
         return true;
     }
+    recordFailedTurnReported(turnId) {
+        if (this.reportedFailedTurns.has(turnId)) {
+            return false;
+        }
+        this.reportedFailedTurns.add(turnId);
+        return true;
+    }
     recordSubagentDelivery(deliveryRunId, messageId, results) {
         if (this.anchoredDeliveryRuns.has(deliveryRunId)) {
             return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teaflask/assistant",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "The AI assistant for your product: drop it into your React app or any page with a script tag.",
   "license": "FSL-1.1-ALv2",
   "author": "Teaflask",