veryfront 0.1.261 → 0.1.263

package/src/src/agent/index.ts

@@ -273,8 +273,10 @@ export {
   normalizeEncodedConversationRunEvents,
 } from "./conversation-run-events.js";
 export {
+  prepareConversationRunChunkEvents,
   prepareConversationRunExternalEvents,
   prepareConversationRunStreamEvents,
+  toConversationRunStreamEvent,
 } from "./conversation-run-event-preparation.js";
 export {
   type ConversationRunMirror,
@@ -379,6 +381,23 @@ export {
   streamDataStreamEvents,
   stripLeadingEmptyObjectPlaceholder,
 } from "./data-stream.js";
+export type {
+  ChatMessageMetadata,
+  ChatMessageMetadataUsage,
+  ChatUiMessageChunk,
+  ChildRunAudit,
+  ChildRunAuditToolCall,
+  ChildRunAuditToolResult,
+} from "../chat/protocol.js";
+export {
+  buildChatStreamChunkMessageMetadata,
+  type BuildChatStreamChunkMessageMetadataInput,
+  dedupeChatUiMessageChunks,
+  extractChatMessageMetadata,
+  normalizeChatMessageMetadata,
+  normalizeChatUiMessageChunk,
+  normalizeChatUiMessageStream,
+} from "../chat/chat-ui-message-helpers.js";
 export {
   expandAllowedRemoteToolNames,
   getProviderNativeToolNames,

package/src/src/agent/runtime-ag-ui-contract.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { parseAgUiJsonRequestOrError } from "./ag-ui-request-shared.js";
 
 const AGENT_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const MAX_TOOL_PARAMETERS_BYTES = 16_384;
@@ -172,32 +173,8 @@ export async function parseAgUiRuntimeRequest(request: Request): Promise<AgUiRun
 export async function parseAgUiRuntimeRequestOrError(
   request: Request,
 ): Promise<AgUiRuntimeRequest | Response> {
-  try {
-    return await parseAgUiRuntimeRequest(request);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return Response.json(
-        {
-          error: "Invalid AG-UI runtime request",
-          details: error.issues.map((issue) => ({
-            path: issue.path,
-            message: issue.message,
-          })),
-        },
-        { status: 400 },
-      );
-    }
-
-    if (error instanceof SyntaxError || error instanceof TypeError) {
-      return Response.json(
-        {
-          error: "Invalid AG-UI runtime request",
-          details: [{ path: [], message: "Malformed JSON request body" }],
-        },
-        { status: 400 },
-      );
-    }
-
-    throw error;
-  }
+  return await parseAgUiJsonRequestOrError(
+    () => parseAgUiRuntimeRequest(request),
+    "Invalid AG-UI runtime request",
+  );
 }

package/src/src/chat/chat-ui-message-helpers.ts

@@ -0,0 +1,232 @@
+import type { ChatMessageMetadata, ChatUiMessageChunk } from "./protocol.js";
+
+type StreamChunkMetadataPart = {
+  type: string;
+  totalUsage?: unknown;
+};
+
+export interface BuildChatStreamChunkMessageMetadataInput {
+  agentId: string;
+  modelId: string;
+  runId?: string;
+  streamingMessageId?: string;
+  part: StreamChunkMetadataPart;
+}
+
+type ReplayState = {
+  content: string;
+  replayOffset: number | null;
+  started: boolean;
+  ended: boolean;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeUsageMetadata(value: unknown): ChatMessageMetadata["usage"] | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const usage = {
+    ...(typeof value.inputTokens === "number" ? { inputTokens: value.inputTokens } : {}),
+    ...(typeof value.outputTokens === "number" ? { outputTokens: value.outputTokens } : {}),
+    ...(typeof value.reasoningTokens === "number"
+      ? { reasoningTokens: value.reasoningTokens }
+      : {}),
+    ...(typeof value.cachedInputTokens === "number"
+      ? { cachedInputTokens: value.cachedInputTokens }
+      : {}),
+  };
+
+  return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+function splitReplayDelta(
+  existing: string,
+  replayOffset: number,
+  delta: string,
+): { emit: string; nextReplayOffset: number | null } {
+  const remaining = existing.slice(replayOffset);
+
+  if (!remaining) {
+    return { emit: delta, nextReplayOffset: null };
+  }
+
+  if (delta === remaining.slice(0, delta.length)) {
+    return { emit: "", nextReplayOffset: replayOffset + delta.length };
+  }
+
+  if (delta.startsWith(remaining)) {
+    return { emit: delta.slice(remaining.length), nextReplayOffset: null };
+  }
+
+  if (remaining.startsWith(delta)) {
+    return { emit: "", nextReplayOffset: replayOffset + delta.length };
+  }
+
+  return { emit: delta, nextReplayOffset: null };
+}
+
+function getReplayState(stateMap: Map<string, ReplayState>, id: string): ReplayState {
+  const existing = stateMap.get(id);
+  if (existing) {
+    return existing;
+  }
+
+  const created: ReplayState = {
+    content: "",
+    replayOffset: null,
+    started: false,
+    ended: false,
+  };
+  stateMap.set(id, created);
+  return created;
+}
+
+export function normalizeChatMessageMetadata(value: unknown): ChatMessageMetadata {
+  if (!isRecord(value)) {
+    return {};
+  }
+
+  const usage = normalizeUsageMetadata(value.usage);
+
+  return {
+    ...(typeof value.createdAt === "string" ? { createdAt: value.createdAt } : {}),
+    ...(typeof value.isStopped === "boolean" ? { isStopped: value.isStopped } : {}),
+    ...(typeof value.isCompleted === "boolean" ? { isCompleted: value.isCompleted } : {}),
+    ...(typeof value.completedAt === "string" ? { completedAt: value.completedAt } : {}),
+    ...(typeof value.agentId === "string" ? { agentId: value.agentId } : {}),
+    ...(typeof value.agentName === "string" ? { agentName: value.agentName } : {}),
+    ...(typeof value.conversationId === "string" ? { conversationId: value.conversationId } : {}),
+    ...(typeof value.modelId === "string" ? { modelId: value.modelId } : {}),
+    ...(typeof value.runId === "string" ? { runId: value.runId } : {}),
+    ...(typeof value.streamingMessageId === "string"
+      ? { streamingMessageId: value.streamingMessageId }
+      : {}),
+    ...(usage ? { usage } : {}),
+  };
+}
+
+export function extractChatMessageMetadata(value: unknown): ChatMessageMetadata | undefined {
+  const normalized = normalizeChatMessageMetadata(value);
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+export function buildChatStreamChunkMessageMetadata(
+  input: BuildChatStreamChunkMessageMetadataInput,
+): ChatMessageMetadata {
+  const baseMetadata: ChatMessageMetadata = {
+    agentId: input.agentId,
+    modelId: input.modelId,
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(input.streamingMessageId ? { streamingMessageId: input.streamingMessageId } : {}),
+  };
+
+  if (input.part.type !== "finish" || !input.part.totalUsage) {
+    return baseMetadata;
+  }
+
+  const usage = normalizeUsageMetadata(input.part.totalUsage);
+  return usage ? { ...baseMetadata, usage } : baseMetadata;
+}
+
+export function normalizeChatUiMessageChunk(
+  chunk: ChatUiMessageChunk<unknown>,
+): ChatUiMessageChunk<ChatMessageMetadata> {
+  switch (chunk.type) {
+    case "start":
+      return {
+        type: "start",
+        ...(chunk.messageId ? { messageId: chunk.messageId } : {}),
+        ...(chunk.messageMetadata !== undefined
+          ? { messageMetadata: normalizeChatMessageMetadata(chunk.messageMetadata) }
+          : {}),
+      };
+    case "message-metadata":
+      return {
+        type: "message-metadata",
+        messageMetadata: normalizeChatMessageMetadata(chunk.messageMetadata),
+      };
+    case "finish":
+      return {
+        type: "finish",
+        ...(chunk.finishReason ? { finishReason: chunk.finishReason } : {}),
+        ...(chunk.messageMetadata !== undefined
+          ? { messageMetadata: normalizeChatMessageMetadata(chunk.messageMetadata) }
+          : {}),
+      };
+    default:
+      return chunk;
+  }
+}
+
+export async function* dedupeChatUiMessageChunks<TMessageMetadata>(
+  stream: AsyncIterable<ChatUiMessageChunk<TMessageMetadata>>,
+): AsyncIterable<ChatUiMessageChunk<TMessageMetadata>> {
+  const textStates = new Map<string, ReplayState>();
+  const reasoningStates = new Map<string, ReplayState>();
+
+  for await (const chunk of stream) {
+    if (chunk.type === "text-start" || chunk.type === "reasoning-start") {
+      const stateMap = chunk.type === "text-start" ? textStates : reasoningStates;
+      const state = getReplayState(stateMap, chunk.id);
+
+      if (state.started) {
+        state.replayOffset = 0;
+        state.ended = false;
+        continue;
+      }
+
+      state.started = true;
+      state.ended = false;
+      yield chunk;
+      continue;
+    }
+
+    if (chunk.type === "text-delta" || chunk.type === "reasoning-delta") {
+      const stateMap = chunk.type === "text-delta" ? textStates : reasoningStates;
+      const state = getReplayState(stateMap, chunk.id);
+      const { emit, nextReplayOffset } = state.replayOffset === null
+        ? { emit: chunk.delta, nextReplayOffset: null as number | null }
+        : splitReplayDelta(state.content, state.replayOffset, chunk.delta);
+
+      state.replayOffset = nextReplayOffset;
+      if (!emit) {
+        continue;
+      }
+
+      state.content += emit;
+      yield {
+        ...chunk,
+        delta: emit,
+      };
+      continue;
+    }
+
+    if (chunk.type === "text-end" || chunk.type === "reasoning-end") {
+      const stateMap = chunk.type === "text-end" ? textStates : reasoningStates;
+      const state = stateMap.get(chunk.id);
+
+      if (!state || state.ended) {
+        continue;
+      }
+
+      state.replayOffset = null;
+      state.ended = true;
+      yield chunk;
+      continue;
+    }
+
+    yield chunk;
+  }
+}
+
+export async function* normalizeChatUiMessageStream(
+  stream: AsyncIterable<ChatUiMessageChunk<unknown>>,
+): AsyncIterable<ChatUiMessageChunk<ChatMessageMetadata>> {
+  for await (const chunk of dedupeChatUiMessageChunks(stream)) {
+    yield normalizeChatUiMessageChunk(chunk);
+  }
+}

package/src/src/chat/index.ts

@@ -212,12 +212,31 @@ export {
   type UseChatResult,
 } from "../agent/react/use-chat/index.js";
 
+export type {
+  ChatMessageMetadata,
+  ChatMessageMetadataUsage,
+  ChatUiMessageChunk,
+  ChildRunAudit,
+  ChildRunAuditToolCall,
+  ChildRunAuditToolResult,
+} from "./protocol.js";
+
 export {
   useAgent,
   type UseAgentOptions,
   type UseAgentResult,
 } from "../agent/react/use-agent.js";
 
+export {
+  buildChatStreamChunkMessageMetadata,
+  type BuildChatStreamChunkMessageMetadataInput,
+  dedupeChatUiMessageChunks,
+  extractChatMessageMetadata,
+  normalizeChatMessageMetadata,
+  normalizeChatUiMessageChunk,
+  normalizeChatUiMessageStream,
+} from "./chat-ui-message-helpers.js";
+
 export {
   useCompletion,
   type UseCompletionOptions,

package/src/src/chat/protocol.ts

@@ -77,6 +77,52 @@ export interface ChatMessage {
   createdAt?: Date | string;
 }
 
+export interface ChatMessageMetadataUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+}
+
+export interface ChildRunAuditToolCall {
+  toolName: string;
+  toolCallId: string;
+  input?: unknown;
+}
+
+export interface ChildRunAuditToolResult {
+  toolName: string;
+  toolCallId: string;
+  input: unknown;
+  output: unknown;
+}
+
+export interface ChildRunAudit {
+  status: "completed" | "failed" | "cancelled" | "stopped";
+  description?: string;
+  steps?: number;
+  durationMs?: number;
+  toolCalls?: ChildRunAuditToolCall[];
+  toolResults?: ChildRunAuditToolResult[];
+  terminalErrorCode?: string | null;
+  terminalErrorMessage?: string | null;
+}
+
+export interface ChatMessageMetadata {
+  createdAt?: string;
+  isStopped?: boolean;
+  isCompleted?: boolean;
+  completedAt?: string;
+  agentId?: string;
+  agentName?: string;
+  conversationId?: string;
+  modelId?: string;
+  runId?: string;
+  streamingMessageId?: string;
+  childRunAudit?: ChildRunAudit;
+  usage?: ChatMessageMetadataUsage;
+}
+
 export type ChatFinishReason =
   | "stop"
   | "length"
@@ -208,3 +254,105 @@ export type ChatStreamEvent =
     type: "error";
     errorText: string;
   };
+
+type MessageLifecycleChunk<TMessageMetadata> =
+  | {
+    type: "start";
+    messageId?: string;
+    messageMetadata?: TMessageMetadata;
+  }
+  | {
+    type: "finish";
+    finishReason?: string;
+    messageMetadata?: TMessageMetadata;
+  }
+  | {
+    type: "message-metadata";
+    messageMetadata: TMessageMetadata;
+  };
+
+type IdChunk<TType extends string> = {
+  type: TType;
+  id: string;
+};
+
+type IdDeltaChunk<TType extends string> = IdChunk<TType> & {
+  delta: string;
+};
+
+type ToolCallChunk<TType extends string> = {
+  type: TType;
+  toolCallId: string;
+};
+
+type NamedToolCallChunk<TType extends string> = ToolCallChunk<TType> & {
+  toolName: string;
+};
+
+type ToolInputChunk<TType extends string> = NamedToolCallChunk<TType> & {
+  input: unknown;
+};
+
+type ToolErrorChunk<TType extends string> = ToolCallChunk<TType> & {
+  errorText: string;
+};
+
+export type ChatUiMessageChunk<TMessageMetadata = ChatMessageMetadata> =
+  | MessageLifecycleChunk<TMessageMetadata>
+  | {
+    type: "start-step";
+  }
+  | {
+    type: "finish-step";
+  }
+  | {
+    type: "abort";
+  }
+  | IdChunk<"reasoning-start">
+  | IdDeltaChunk<"reasoning-delta">
+  | IdChunk<"reasoning-end">
+  | IdChunk<"text-start">
+  | IdDeltaChunk<"text-delta">
+  | IdChunk<"text-end">
+  | {
+    type: "source-url";
+    sourceId: string;
+    url: string;
+    title?: string;
+  }
+  | {
+    type: "source-document";
+    sourceId: string;
+    mediaType: string;
+    title: string;
+    filename?: string;
+  }
+  | {
+    type: "file";
+    mediaType: string;
+    url: string;
+  }
+  | NamedToolCallChunk<"tool-input-start">
+  | (ToolCallChunk<"tool-input-delta"> & {
+    inputTextDelta: string;
+  })
+  | ToolInputChunk<"tool-input-available">
+  | (ToolInputChunk<"tool-input-error"> & {
+    errorText: string;
+  })
+  | (ToolCallChunk<"tool-output-available"> & {
+    output: unknown;
+  })
+  | ToolErrorChunk<"tool-output-error">
+  | ToolCallChunk<"tool-output-denied">
+  | (ToolCallChunk<"tool-approval-request"> & {
+    approvalId: string;
+  })
+  | {
+    type: "error";
+    errorText: string;
+  }
+  | {
+    type: `data-${string}`;
+    data: unknown;
+  };

package/src/src/provider/runtime-loader/provider-http.ts

@@ -0,0 +1,207 @@
+import { readRecord } from "./provider-records.js";
+
+export type ProviderKind = "anthropic" | "openai" | "google";
+
+/**
+ * Base class for typed provider errors. The `retryable` flag is the
+ * primary signal for callers (or a retry wrapper) to decide whether to
+ * re-issue the request. `retryAfterMs` is set when the provider gave an
+ * explicit delay hint (Retry-After header, Retry-Info trailer).
+ */
+export class ProviderError extends Error {
+  readonly provider: ProviderKind;
+  readonly status: number;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+
+  constructor(options: {
+    provider: ProviderKind;
+    status: number;
+    message: string;
+    retryable: boolean;
+    retryAfterMs?: number;
+  }) {
+    super(options.message);
+    this.name = new.target.name;
+    this.provider = options.provider;
+    this.status = options.status;
+    this.retryable = options.retryable;
+    if (options.retryAfterMs !== undefined) {
+      this.retryAfterMs = options.retryAfterMs;
+    }
+  }
+}
+
+/** Provider reports it is overloaded (Anthropic 529, OpenAI/Google 503). */
+export class ProviderOverloadedError extends ProviderError {}
+
+/** Provider is rate limiting this API key (OpenAI/Google 429 with Retry-After). */
+export class ProviderRateLimitError extends ProviderError {}
+
+/** Provider account quota is exhausted — non-retryable. */
+export class ProviderQuotaError extends ProviderError {}
+
+/** Non-retryable 4xx/5xx that doesn't fit another bucket. */
+export class ProviderRequestError extends ProviderError {}
+
+function parseRetryAfterMs(header: string | null): number | undefined {
+  if (!header) return undefined;
+  const asNumber = Number(header);
+  if (Number.isFinite(asNumber) && asNumber >= 0) {
+    return Math.round(asNumber * 1000);
+  }
+  // HTTP-date form (rare in practice for LLM providers).
+  const parsed = Date.parse(header);
+  if (!Number.isNaN(parsed)) {
+    return Math.max(0, parsed - Date.now());
+  }
+  return undefined;
+}
+
+/**
+ * Inspect a non-2xx response and build the most specific ProviderError
+ * subclass we can. Reads the response body as text (it's already dead
+ * on the wire by this point). Body classification handles the cases
+ * where HTTP status alone is ambiguous — notably OpenAI
+ * `insufficient_quota` vs `rate_limit_exceeded` both arriving as 429.
+ */
+async function buildProviderError(
+  provider: ProviderKind,
+  response: Response,
+): Promise<ProviderError> {
+  const rawBody = await response.text();
+  const message = rawBody.trim() || `${response.status} ${response.statusText}`.trim();
+  const status = response.status;
+  const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+
+  const parsedBody = (() => {
+    try {
+      return JSON.parse(rawBody) as Record<string, unknown>;
+    } catch {
+      return undefined;
+    }
+  })();
+  const errorRecord = readRecord(parsedBody?.error);
+  const errorCode = typeof errorRecord?.code === "string"
+    ? errorRecord.code
+    : typeof errorRecord?.type === "string"
+    ? errorRecord.type
+    : typeof errorRecord?.status === "string"
+    ? errorRecord.status
+    : undefined;
+
+  // Anthropic 529 = overloaded. Anthropic surfaces this with
+  // { error: { type: "overloaded_error" } } in the body.
+  if (provider === "anthropic" && status === 529) {
+    return new ProviderOverloadedError({
+      provider,
+      status,
+      message,
+      retryable: true,
+      ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    });
+  }
+
+  // OpenAI / Google 503 = overloaded.
+  if ((provider === "openai" || provider === "google") && status === 503) {
+    return new ProviderOverloadedError({
+      provider,
+      status,
+      message,
+      retryable: true,
+      ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    });
+  }
+
+  // OpenAI 429 splits based on the error code in the body:
+  //  - insufficient_quota → hard quota, non-retryable
+  //  - rate_limit_exceeded / tokens_per_min_exceeded → retry with Retry-After
+  if (provider === "openai" && status === 429) {
+    if (errorCode === "insufficient_quota") {
+      return new ProviderQuotaError({
+        provider,
+        status,
+        message,
+        retryable: false,
+      });
+    }
+    return new ProviderRateLimitError({
+      provider,
+      status,
+      message,
+      retryable: true,
+      ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    });
+  }
+
+  // Google 429 RESOURCE_EXHAUSTED is almost always the daily free-tier
+  // quota — surface as a hard quota error so callers don't hot-loop on
+  // retries that can't possibly succeed until midnight UTC.
+  if (provider === "google" && status === 429) {
+    if (errorCode === "RESOURCE_EXHAUSTED") {
+      return new ProviderQuotaError({
+        provider,
+        status,
+        message,
+        retryable: false,
+      });
+    }
+    return new ProviderRateLimitError({
+      provider,
+      status,
+      message,
+      retryable: true,
+      ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    });
+  }
+
+  return new ProviderRequestError({
+    provider,
+    status,
+    message,
+    retryable: false,
+  });
+}
+
+export async function requestJson(options: {
+  url: string;
+  fetchImpl: typeof globalThis.fetch;
+  init: RequestInit;
+  providerLabel: string;
+  providerKind: ProviderKind;
+}): Promise<unknown> {
+  const response = await options.fetchImpl(options.url, options.init);
+  if (!response.ok) {
+    const err = await buildProviderError(options.providerKind, response);
+    err.message = `${options.providerLabel} request failed: ${err.message}`;
+    throw err;
+  }
+
+  return response.json();
+}
+
+export async function requestStream(options: {
+  url: string;
+  fetchImpl: typeof globalThis.fetch;
+  init: RequestInit;
+  providerLabel: string;
+  providerKind: ProviderKind;
+}): Promise<ReadableStream<Uint8Array>> {
+  const response = await options.fetchImpl(options.url, options.init);
+  if (!response.ok) {
+    const err = await buildProviderError(options.providerKind, response);
+    err.message = `${options.providerLabel} request failed: ${err.message}`;
+    throw err;
+  }
+
+  if (!response.body) {
+    throw new ProviderRequestError({
+      provider: options.providerKind,
+      status: response.status,
+      message: `${options.providerLabel} request failed: stream body missing`,
+      retryable: false,
+    });
+  }
+
+  return response.body;
+}