vibefast-cli 0.7.12 → 0.7.14

package/recipes/chatbot/packages/backend/convex/chatbot/streaming.ts

@@ -0,0 +1,422 @@
+import type { CoreMessage, FilePart, ImagePart, TextPart } from 'ai';
+
+import { components, internal } from '../_generated/api';
+import type { Doc, Id } from '../_generated/dataModel';
+import type { ActionCtx } from '../_generated/server';
+import { agent, resolveChatModel } from '../agents';
+import { buildUserContent } from './content';
+import { createTelemetryTracker } from './telemetry';
+import {
+  extractToolCallId,
+  extractToolName,
+  isTextDelta,
+  isToolCall,
+  isToolCallStreamingStart,
+  isToolResult,
+  MAX_PENDING_CHARS,
+  mergeToolResults,
+  SENTENCE_DELIMITER,
+  toolLabel,
+  type ToolCall,
+  type ToolResult,
+  type ToolCallPart,
+  type ToolCallStreamingStartPart,
+  type ToolResultPart,
+  type ToolStreamPart,
+} from './tools';
+
+type AgentTools = NonNullable<(typeof agent)['options']['tools']>;
+
+type StatusRecord =
+  | null
+  | { type: 'thinking'; label: string | null }
+  | {
+      type: 'tool';
+      label: string | null;
+      toolName: string | null;
+      toolCallId: string | null;
+    };
+
+export type RunStreamingArgs = {
+  streamId: string;
+  conversationId: Id<'conversations'>;
+  agentThreadId: string;
+  userMessageId: Id<'messages'>;
+  preferredModel?: string;
+  agentSessionId: Id<'agentSessions'>;
+};
+
+const STREAM_TIMEOUT_MS = 120_000;
+
+function getToolCallId(part: ToolCallStreamingStartPart | ToolCallPart) {
+  return extractToolCallId(part) ?? extractToolName(part) ?? 'tool';
+}
+
+async function applyStatus(
+  ctx: ActionCtx,
+  agentSessionId: Id<'agentSessions'>,
+  status:
+    | { type: 'thinking'; label?: string }
+    | {
+        type: 'tool';
+        toolName: string;
+        label?: string;
+        toolCallId?: string;
+      }
+    | null,
+  lastStatus: StatusRecord,
+  setLastStatus: (s: StatusRecord) => void,
+) {
+  const normalized: StatusRecord = status
+    ? status.type === 'tool'
+      ? {
+          type: 'tool',
+          label: status.label ?? null,
+          toolName: status.toolName,
+          toolCallId: status.toolCallId ?? null,
+        }
+      : {
+          type: 'thinking',
+          label: status.label ?? null,
+        }
+    : null;
+
+  if (
+    normalized &&
+    lastStatus &&
+    normalized.type === lastStatus.type &&
+    normalized.label === lastStatus.label &&
+    (normalized.type !== 'tool' ||
+      (lastStatus.type === 'tool' &&
+        normalized.toolName === lastStatus.toolName &&
+        normalized.toolCallId === lastStatus.toolCallId))
+  ) {
+    return;
+  }
+
+  if (normalized === null && lastStatus === null) {
+    return;
+  }
+
+  setLastStatus(normalized);
+
+  const payload = normalized
+    ? {
+        type: normalized.type,
+        label: normalized.label ?? undefined,
+        toolName:
+          normalized.type === 'tool'
+            ? (normalized.toolName ?? undefined)
+            : undefined,
+      }
+    : null;
+
+  await ctx.runMutation(internal.chatbotAgent.updateSessionStatus, {
+    agentSessionId,
+    status: payload,
+  });
+}
+
+export async function handleRunStreaming(ctx: ActionCtx, args: RunStreamingArgs) {
+  const telemetry = createTelemetryTracker('runStreaming', {
+    streamId: args.streamId,
+    conversationId: args.conversationId,
+    agentSessionId: args.agentSessionId,
+  });
+
+  let telemetryStatus: 'ok' | 'error' = 'ok';
+  const telemetryExtra: Record<string, unknown> = {};
+  let failureHandled = false;
+
+  const inferErrorMessage = (raw: unknown): string | undefined => {
+    if (!raw) return undefined;
+    if (typeof raw === 'string') {
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+          if (typeof parsed.error === 'string') {
+            return parsed.error;
+          }
+          if (typeof parsed.message === 'string') {
+            return parsed.message;
+          }
+        }
+      } catch {
+        // ignore
+      }
+      const trimmed = raw.trim();
+      if (trimmed.length > 0 && trimmed.length <= 300) {
+        return trimmed;
+      }
+      return undefined;
+    }
+    if (raw instanceof Error) {
+      return raw.message;
+    }
+    return undefined;
+  };
+
+  const markFailure = async (
+    maybeMessage: unknown,
+    extra?: Record<string, unknown>,
+  ) => {
+    telemetryStatus = 'error';
+    if (extra) {
+      Object.assign(telemetryExtra, extra);
+    }
+    failureHandled = true;
+    const message =
+      inferErrorMessage(maybeMessage) ??
+      'Sorry, I ran into a technical issue while replying. Please try again.';
+
+    try {
+      await ctx.runMutation(
+        components.persistentTextStreaming.lib.setStreamStatus,
+        {
+          streamId: args.streamId,
+          status: 'error',
+        },
+      );
+    } catch (statusError) {
+      console.error('[chatbotAgent] Failed to update stream status to error', {
+        streamId: args.streamId,
+        statusError,
+      });
+    }
+
+    await ctx.runMutation(internal.chatbotAgent.markStreamFailed, {
+      agentSessionId: args.agentSessionId,
+      conversationId: args.conversationId,
+      streamId: args.streamId,
+      errorMessage: message,
+    });
+  };
+
+  try {
+    telemetry?.mark('conversation.lookup');
+    const conversation = await ctx.runQuery(
+      internal.chatbotAgent.getConversationForStreaming,
+      { conversationId: args.conversationId },
+    );
+    if (!conversation) {
+      await markFailure('Conversation not found.', {
+        reason: 'conversationMissing',
+      });
+      return;
+    }
+
+    telemetry?.mark('session.lookup');
+    const session = await ctx.runQuery(
+      internal.chatbotAgent.getAgentSessionById,
+      { agentSessionId: args.agentSessionId },
+    );
+    if (!session) {
+      await markFailure('Agent session missing.', {
+        reason: 'sessionMissing',
+      });
+      return;
+    }
+
+    telemetry?.mark('message.lookup');
+    const message = await ctx.runQuery(
+      internal.chatbotAgent.getMessageForStreaming,
+      { messageId: args.userMessageId },
+    );
+    if (!message || message.conversationId !== args.conversationId) {
+      await markFailure('User message missing.', {
+        reason: 'userMessageMissing',
+      });
+      return;
+    }
+
+    const { model, provider, modelId } = resolveChatModel(
+      args.preferredModel ?? session.preferredModel ?? undefined,
+    );
+    telemetryExtra.provider = provider;
+    telemetryExtra.modelId = modelId;
+    telemetry?.mark('model.resolved', { provider, modelId });
+
+    const userContent = await buildUserContent(ctx, message as Doc<'messages'>);
+    telemetry?.mark('content.resolved', {
+      hasAttachments: Boolean(message.attachments?.length),
+    });
+
+    const { thread } = await agent.continueThread(ctx, {
+      threadId: args.agentThreadId,
+      userId: conversation.userId,
+    });
+    telemetry?.mark('agent.threadReady');
+
+    const messages: CoreMessage[] = [
+      {
+        role: 'user',
+        content: userContent as string | (TextPart | ImagePart | FilePart)[],
+      },
+    ];
+
+    let streamResult;
+    try {
+      streamResult = await thread.streamText(
+        {
+          model,
+          messages,
+        },
+        {
+          storageOptions: {
+            saveMessages: 'promptAndOutput',
+          },
+        },
+      );
+    } catch (streamInitError) {
+      console.error('[chatbotAgent] Failed to initialize stream', {
+        streamInitError,
+        provider,
+        modelId,
+      });
+      await markFailure(streamInitError, {
+        reason: 'streamInitFailed',
+        provider,
+        modelId,
+      });
+      return;
+    }
+
+    telemetry?.mark('agent.stream.started');
+
+    let lastStatus: StatusRecord = { type: 'thinking', label: 'Thinking…' };
+    const setLastStatus = (status: StatusRecord) => {
+      lastStatus = status;
+    };
+
+    let finalResponse = '';
+    let pendingChunk = '';
+    let wroteChunk = false;
+
+    const flushChunk = async (final: boolean) => {
+      const textToWrite = pendingChunk;
+      pendingChunk = '';
+      if (!final && textToWrite.length === 0) {
+        return;
+      }
+      await ctx.runMutation(components.persistentTextStreaming.lib.addChunk, {
+        streamId: args.streamId,
+        text: textToWrite,
+        final,
+      });
+      wroteChunk = true;
+    };
+
+    const streamPromise = (async () => {
+      // AI SDK v5 exposes normalized textStream chunks; consume those directly.
+      for await (const delta of streamResult.textStream) {
+        if (!delta) {
+          continue;
+        }
+        finalResponse += delta;
+        pendingChunk += delta;
+
+        if (lastStatus !== null) {
+          await applyStatus(ctx, args.agentSessionId, null, lastStatus, setLastStatus);
+        }
+
+        if (
+          SENTENCE_DELIMITER.test(delta) ||
+          pendingChunk.length >= MAX_PENDING_CHARS
+        ) {
+          await flushChunk(false);
+        }
+      }
+    })();
+
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error('Stream timed out after 2 minutes'));
+      }, STREAM_TIMEOUT_MS);
+    });
+
+    try {
+      await Promise.race([streamPromise, timeoutPromise]);
+    } catch (streamError) {
+      console.error('[chatbotAgent] Stream failed or timed out', {
+        streamError,
+        streamId: args.streamId,
+      });
+      telemetryExtra.streamError =
+        streamError instanceof Error
+          ? streamError.message
+          : String(streamError);
+      await markFailure(streamError, {
+        reason: 'streamReadFailed',
+      });
+      return;
+    }
+
+    if (pendingChunk.length > 0) {
+      await flushChunk(true);
+    } else {
+      await ctx.runMutation(components.persistentTextStreaming.lib.setStreamStatus, {
+        streamId: args.streamId,
+        status: wroteChunk ? 'done' : 'done',
+      });
+    }
+
+    await applyStatus(ctx, args.agentSessionId, null, lastStatus, setLastStatus);
+
+    telemetry?.mark('agent.stream.completed', {
+      responseLength: finalResponse.length,
+    });
+
+    const [usage, toolCalls, toolResults] = await Promise.all([
+      streamResult.usage.catch(() => undefined),
+      streamResult.toolCalls.catch(() => [] as ToolCall[]),
+      streamResult.toolResults.catch(() => [] as ToolResult[]),
+    ]);
+
+    const serializedTools = mergeToolResults(
+      (toolCalls ?? []) as ToolCall[],
+      (toolResults ?? []) as ToolResult[],
+    );
+
+    await ctx.runMutation(internal.chatbotAgent.saveAssistantMessage, {
+      agentSessionId: args.agentSessionId,
+      conversationId: args.conversationId,
+      streamId: args.streamId,
+      text: finalResponse,
+      provider,
+      modelId,
+      usage: usage
+        ? {
+            promptTokens: usage.promptTokens ?? undefined,
+            completionTokens: usage.completionTokens ?? undefined,
+            totalTokens: usage.totalTokens ?? undefined,
+          }
+        : undefined,
+      toolCalls: serializedTools,
+    });
+
+    telemetryExtra.responseLength = finalResponse.length;
+    telemetryStatus = 'ok';
+  } catch (error) {
+    console.error('[chatbotAgent] runStreaming caught error', {
+      error,
+      failureHandled,
+      streamId: args.streamId,
+      conversationId: args.conversationId,
+    });
+
+    if (!failureHandled) {
+      try {
+        await markFailure(error);
+        console.log('[chatbotAgent] markFailure completed successfully');
+      } catch (markFailureError) {
+        console.error('[chatbotAgent] markFailure itself failed!', {
+          markFailureError,
+          originalError: error,
+        });
+      }
+    }
+    telemetryExtra.error = error instanceof Error ? error.message : String(error);
+  } finally {
+    telemetry?.finalize(telemetryStatus, telemetryExtra);
+  }
+}

package/recipes/chatbot/packages/backend/convex/chatbot/telemetry.ts

@@ -0,0 +1,56 @@
+import { getChatTelemetryMode, type TelemetryMode } from '../lib/telemetry';
+
+const DEFAULT_TELEMETRY_SAMPLE = 0.1;
+
+type TelemetryCheckpoint = {
+  label: string;
+  at: number;
+  data?: Record<string, unknown>;
+};
+
+export type TelemetryTracker = {
+  mark: (label: string, data?: Record<string, unknown>) => void;
+  finalize: (status: 'ok' | 'error', extra?: Record<string, unknown>) => void;
+};
+
+export function createTelemetryTracker(
+  event: string,
+  baseContext: Record<string, unknown>,
+  sampleProbability = DEFAULT_TELEMETRY_SAMPLE,
+): TelemetryTracker | null {
+  const mode: TelemetryMode = getChatTelemetryMode();
+  const shouldTrack =
+    mode === 'debug' ||
+    (mode === 'sample' && Math.random() < sampleProbability);
+
+  if (!shouldTrack) {
+    return null;
+  }
+
+  const start = Date.now();
+  const checkpoints: TelemetryCheckpoint[] = [{ label: 'start', at: start }];
+
+  return {
+    mark(label, data) {
+      checkpoints.push({ label, at: Date.now(), data });
+    },
+    finalize(status, extra) {
+      const finishedAt = Date.now();
+      const timeline = checkpoints.map((checkpoint) => ({
+        label: checkpoint.label,
+        msFromStart: checkpoint.at - start,
+        ...(checkpoint.data ?? {}),
+      }));
+
+      console.log('[chatbotAgent][telemetry]', {
+        event,
+        mode,
+        status,
+        totalMs: finishedAt - start,
+        ...baseContext,
+        ...(extra ?? {}),
+        timeline,
+      });
+    },
+  };
+}

package/recipes/chatbot/packages/backend/convex/chatbot/tools.ts

@@ -0,0 +1,128 @@
+export const SENTENCE_DELIMITER = /[.!?]/;
+export const MAX_PENDING_CHARS = 180;
+
+export type ToolCall = {
+  toolName: string;
+  args?: unknown;
+  toolCallId?: string;
+  id?: string;
+};
+
+export type ToolResult = {
+  toolCallId?: string;
+  id?: string;
+  result?: unknown;
+};
+
+const TOOL_STATUS_LABELS: Record<string, string> = {
+  knowledgeRetrieval: 'Looking through knowledge…',
+  tavilySearch: 'Searching the web…',
+  userProfile: 'Checking your profile…',
+};
+
+export function toolLabel(toolName: string) {
+  return TOOL_STATUS_LABELS[toolName] ?? `Using ${toolName}`;
+}
+
+export function mergeToolResults(
+  toolCalls: ToolCall[],
+  toolResults: ToolResult[],
+) {
+  if (!toolCalls?.length) {
+    return [];
+  }
+
+  const resultByCallId = new Map<string, unknown>();
+
+  for (const result of toolResults ?? []) {
+    const key =
+      (result as { toolCallId?: string }).toolCallId ??
+      (result as { id?: string }).id;
+    if (key) {
+      resultByCallId.set(key, (result as { result?: unknown }).result);
+    }
+  }
+
+  return toolCalls.map((call) => {
+    const callId =
+      (call as { id?: string }).id ??
+      (call as { toolCallId?: string }).toolCallId ??
+      call.toolName;
+
+    return {
+      toolName: call.toolName ?? callId ?? 'tool',
+      args: (call as { args?: unknown }).args ?? null,
+      result: callId ? resultByCallId.get(callId) : undefined,
+    };
+  });
+}
+
+export type TextDeltaPart = { type: 'text-delta'; textDelta?: string };
+export type ToolCallStreamingStartPart = {
+  type: 'tool-call-streaming-start';
+  toolCallId: string;
+  toolName: string;
+};
+export type ToolCallPart = {
+  type: 'tool-call';
+  toolCallId?: string;
+  id?: string;
+  toolName: string;
+};
+export type ToolResultPart = {
+  type: 'tool-result';
+  toolCallId?: string;
+  id?: string;
+  toolName?: string;
+};
+
+export type ToolStreamPart =
+  | TextDeltaPart
+  | ToolCallStreamingStartPart
+  | ToolCallPart
+  | ToolResultPart
+  | { type: string; [key: string]: unknown };
+
+export function isTextDelta(part: ToolStreamPart): part is TextDeltaPart {
+  return part.type === 'text-delta';
+}
+
+export function isToolCallStreamingStart(
+  part: ToolStreamPart,
+): part is ToolCallStreamingStartPart {
+  const candidate = part as Partial<ToolCallStreamingStartPart>;
+  return (
+    part.type === 'tool-call-streaming-start' &&
+    typeof candidate.toolCallId === 'string' &&
+    typeof candidate.toolName === 'string'
+  );
+}
+
+export function isToolCall(part: ToolStreamPart): part is ToolCallPart {
+  return part.type === 'tool-call' && typeof (part as ToolCallPart).toolName === 'string';
+}
+
+export function isToolResult(part: ToolStreamPart): part is ToolResultPart {
+  return part.type === 'tool-result';
+}
+
+export function extractToolCallId(
+  part: ToolCallPart | ToolResultPart | ToolCallStreamingStartPart,
+): string | null {
+  if ('toolCallId' in part && typeof part.toolCallId === 'string') {
+    return part.toolCallId;
+  }
+  if ('id' in part && typeof part.id === 'string') {
+    return part.id;
+  }
+  return null;
+}
+
+export function extractToolName(
+  part: ToolCallPart | ToolCallStreamingStartPart,
+): string | null {
+  if ('toolName' in part && typeof part.toolName === 'string') {
+    return part.toolName;
+  }
+  return null;
+}