veryfront 0.1.258 → 0.1.259

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.258",
+  "version": "0.1.259",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [

package/src/src/agent/ag-ui-browser-finalize-tracker.ts

@@ -0,0 +1,65 @@
+import {
+  type AgUiBrowserEncodedEvent,
+  type AgUiBrowserRunFinishedMetadata,
+  buildAgUiBrowserFinalizeResponse,
+} from "./ag-ui-browser-encoder.js";
+import type { AgentResponse } from "./types.js";
+
+export interface AgUiBrowserFinalizeTracker<TChunk> {
+  observeChunk: (chunk: TChunk) => void;
+  observeEncodedEvents: (events: readonly AgUiBrowserEncodedEvent[]) => void;
+  getFinalResponse: () => AgentResponse | null;
+}
+
+export interface CreateAgUiBrowserFinalizeTrackerOptions<TChunk> {
+  getMetadataFromChunk: (
+    chunk: TChunk,
+  ) => Partial<AgUiBrowserRunFinishedMetadata> | null | undefined;
+}
+
+export function createAgUiBrowserFinalizeTracker<TChunk>(
+  options: CreateAgUiBrowserFinalizeTrackerOptions<TChunk>,
+): AgUiBrowserFinalizeTracker<TChunk> {
+  let sawRunError = false;
+  const metadata: AgUiBrowserRunFinishedMetadata = {};
+
+  return {
+    observeChunk: (chunk) => {
+      const nextMetadata = options.getMetadataFromChunk(chunk);
+      if (!nextMetadata) {
+        return;
+      }
+
+      if (typeof nextMetadata.provider === "string") {
+        metadata.provider = nextMetadata.provider;
+      }
+      if (typeof nextMetadata.model === "string") {
+        metadata.model = nextMetadata.model;
+      }
+      if (typeof nextMetadata.inputTokens === "number") {
+        metadata.inputTokens = nextMetadata.inputTokens;
+      }
+      if (typeof nextMetadata.outputTokens === "number") {
+        metadata.outputTokens = nextMetadata.outputTokens;
+      }
+      if (typeof nextMetadata.totalTokens === "number") {
+        metadata.totalTokens = nextMetadata.totalTokens;
+      }
+      if (typeof nextMetadata.finishReason === "string") {
+        metadata.finishReason = nextMetadata.finishReason;
+      }
+    },
+    observeEncodedEvents: (events) => {
+      if (events.some((event) => event.event === "RunError")) {
+        sawRunError = true;
+      }
+    },
+    getFinalResponse: () => {
+      if (sawRunError) {
+        return null;
+      }
+
+      return buildAgUiBrowserFinalizeResponse(metadata);
+    },
+  };
+}

package/src/src/agent/ag-ui-chunk-encoder-bridge.ts

@@ -0,0 +1,34 @@
+import {
+  type AgentResponse,
+  type AgUiBrowserEncodedEvent,
+  type AgUiBrowserEncoderState,
+  type AgUiRuntimeStreamEvent,
+  createAgUiBrowserEncoderState,
+  finalizeAgUiBrowserEvents,
+  mapRuntimeStreamEventToAgUiBrowserEvents,
+} from "./index.js";
+
+export interface AgUiChunkEncoderBridge<TChunk> {
+  encode: (chunk: TChunk) => AgUiBrowserEncodedEvent[];
+  finalize: (response: AgentResponse | null) => AgUiBrowserEncodedEvent[];
+  state: AgUiBrowserEncoderState;
+}
+
+export interface CreateAgUiChunkEncoderBridgeOptions<TChunk> {
+  getRuntimeEvents: (chunk: TChunk) => readonly AgUiRuntimeStreamEvent[];
+}
+
+export function createAgUiChunkEncoderBridge<TChunk>(
+  options: CreateAgUiChunkEncoderBridgeOptions<TChunk>,
+): AgUiChunkEncoderBridge<TChunk> {
+  const state = createAgUiBrowserEncoderState();
+
+  return {
+    state,
+    encode: (chunk) =>
+      options.getRuntimeEvents(chunk).flatMap((event) =>
+        mapRuntimeStreamEventToAgUiBrowserEvents(state, event)
+      ),
+    finalize: (response) => finalizeAgUiBrowserEvents(state, response),
+  };
+}

package/src/src/agent/ag-ui-host-support.ts

@@ -236,3 +236,14 @@ export function createAgUiSseErrorResponse(event: AgUiSseEvent, status: number):
     },
   });
 }
+
+export function createAgUiSseResponse(stream: ReadableStream<Uint8Array>): Response {
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}

package/src/src/agent/ag-ui-runtime-browser-response.ts

@@ -0,0 +1,41 @@
+import {
+  type AgUiBrowserResponseEncoder,
+  type AgUiBrowserResponseExecution,
+  createAgUiBrowserResponseStream,
+} from "./ag-ui-browser-response-stream.js";
+import { createAgUiSseResponse } from "./ag-ui-host-support.js";
+import {
+  type AgUiRuntimeRequest,
+  normalizeAgUiBrowserRuntimeRequest,
+} from "./runtime-ag-ui-contract.js";
+import type { AgentResponse } from "./types.js";
+
+export interface CreateAgUiRuntimeBrowserResponseInput<TChunk, TState> {
+  agUiInput: AgUiRuntimeRequest;
+  defaults?: {
+    threadId?: string;
+    runId?: string;
+  };
+  agentId: string;
+  execution: AgUiBrowserResponseExecution<TChunk>;
+  encoder: AgUiBrowserResponseEncoder<TChunk>;
+  initialState: TState;
+  onChunk?: (state: TState, chunk: TChunk) => void;
+  getFinalResponse?: (state: TState) => AgentResponse | null;
+}
+
+export function createAgUiRuntimeBrowserResponse<TChunk, TState>(
+  input: CreateAgUiRuntimeBrowserResponseInput<TChunk, TState>,
+): Response {
+  const stream = createAgUiBrowserResponseStream({
+    agUiInput: normalizeAgUiBrowserRuntimeRequest(input.agUiInput, input.defaults),
+    agentId: input.agentId,
+    execution: input.execution,
+    encoder: input.encoder,
+    initialState: input.initialState,
+    ...(input.onChunk ? { onChunk: input.onChunk } : {}),
+    ...(input.getFinalResponse ? { getFinalResponse: input.getFinalResponse } : {}),
+  });
+
+  return createAgUiSseResponse(stream);
+}

package/src/src/agent/ag-ui-runtime-event-encoder.ts

@@ -0,0 +1,71 @@
+import {
+  type AgentResponse,
+  type AgUiBrowserEncodedEvent,
+  type AgUiBrowserEncoderState,
+  type AgUiBrowserRunFinishedMetadata,
+  type AgUiRuntimeStreamEvent,
+  createAgUiBrowserEncoderState,
+  finalizeAgUiBrowserEvents,
+  mapRuntimeStreamEventToAgUiBrowserEvents,
+} from "./index.js";
+
+export interface AgUiRuntimeEventEncoder {
+  state: AgUiBrowserEncoderState;
+  encode: (event: AgUiRuntimeStreamEvent) => AgUiBrowserEncodedEvent[];
+  finalize: (response: AgentResponse | null) => AgUiBrowserEncodedEvent[];
+}
+
+export interface CreateAgUiRuntimeEventEncoderOptions {
+  initialMetadata?: Partial<AgUiBrowserRunFinishedMetadata>;
+}
+
+export function createAgUiRuntimeEventEncoder(
+  options: CreateAgUiRuntimeEventEncoderOptions = {},
+): AgUiRuntimeEventEncoder {
+  const state = createAgUiBrowserEncoderState();
+  const toolInputs = new Map<string, unknown>();
+
+  Object.assign(state.metadata, options.initialMetadata ?? {});
+
+  return {
+    state,
+    encode: (event) => {
+      if (
+        (event.type === "tool-input-available" || event.type === "tool-input-error") &&
+        typeof event.toolCallId === "string"
+      ) {
+        toolInputs.set(event.toolCallId, event.input);
+      }
+
+      const encodedEvents = mapRuntimeStreamEventToAgUiBrowserEvents(state, event).map((next) => {
+        if (
+          next.event !== "ToolCallResult" ||
+          typeof next.payload.toolCallId !== "string" ||
+          !toolInputs.has(next.payload.toolCallId)
+        ) {
+          return next;
+        }
+
+        return {
+          ...next,
+          payload: {
+            ...next.payload,
+            input: toolInputs.get(next.payload.toolCallId),
+          },
+        };
+      });
+
+      if (
+        (event.type === "tool-output-available" ||
+          event.type === "tool-output-error" ||
+          event.type === "tool-output-denied") &&
+        typeof event.toolCallId === "string"
+      ) {
+        toolInputs.delete(event.toolCallId);
+      }
+
+      return encodedEvents;
+    },
+    finalize: (response) => finalizeAgUiBrowserEvents(state, response),
+  };
+}

package/src/src/agent/ag-ui-tracked-browser-response.ts

@@ -0,0 +1,42 @@
+import type { AgUiBrowserEncodedEvent } from "./ag-ui-browser-encoder.js";
+import type { AgUiBrowserFinalizeTracker } from "./ag-ui-browser-finalize-tracker.js";
+import type { AgUiChunkEncoderBridge } from "./ag-ui-chunk-encoder-bridge.js";
+import {
+  createAgUiRuntimeBrowserResponse,
+  type CreateAgUiRuntimeBrowserResponseInput,
+} from "./ag-ui-runtime-browser-response.js";
+import type { AgentResponse } from "./types.js";
+
+export interface CreateAgUiTrackedBrowserResponseInput<TChunk> extends
+  Omit<
+    CreateAgUiRuntimeBrowserResponseInput<TChunk, null>,
+    "encoder" | "initialState" | "onChunk" | "getFinalResponse"
+  > {
+  chunkEncoder: Pick<AgUiChunkEncoderBridge<TChunk>, "encode" | "finalize">;
+  finalizeTracker: Pick<
+    AgUiBrowserFinalizeTracker<TChunk>,
+    "observeChunk" | "observeEncodedEvents" | "getFinalResponse"
+  >;
+}
+
+export function createAgUiTrackedBrowserResponse<TChunk>(
+  input: CreateAgUiTrackedBrowserResponseInput<TChunk>,
+): Response {
+  return createAgUiRuntimeBrowserResponse({
+    ...input,
+    encoder: {
+      encode: (chunk) => {
+        const events = input.chunkEncoder.encode(chunk);
+        input.finalizeTracker.observeEncodedEvents(events);
+        return events;
+      },
+      finalize: (response: AgentResponse | null): AgUiBrowserEncodedEvent[] =>
+        input.chunkEncoder.finalize(response),
+    },
+    initialState: null,
+    onChunk: (_state, chunk) => {
+      input.finalizeTracker.observeChunk(chunk);
+    },
+    getFinalResponse: () => input.finalizeTracker.getFinalResponse(),
+  });
+}

package/src/src/agent/hosted-response-stream.ts

@@ -0,0 +1,87 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { type HostedLifecycleExecution, runHostedLifecycle } from "./hosted-lifecycle.js";
+
+export interface HostedResponseStreamWriter<TChunk> {
+  write: (chunk: TChunk) => void;
+}
+
+export interface HostedResponseStreamHeartbeatState {
+  heartbeatCount: number;
+  elapsedSeconds: number;
+}
+
+export interface HostedResponseStreamHeartbeat<TChunk> {
+  intervalMs?: number;
+  buildChunk: () => TChunk;
+  onBeat?: (state: HostedResponseStreamHeartbeatState) => void;
+  onStop?: (state: HostedResponseStreamHeartbeatState) => void;
+}
+
+export interface RunHostedResponseStreamWithHeartbeatOptions<TChunk> {
+  execution: HostedLifecycleExecution<TChunk>;
+  writer: HostedResponseStreamWriter<TChunk>;
+  heartbeat?: HostedResponseStreamHeartbeat<TChunk>;
+  runId?: string;
+}
+
+function getHeartbeatState(
+  startedAt: number,
+  heartbeatCount: number,
+): HostedResponseStreamHeartbeatState {
+  return {
+    heartbeatCount,
+    elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+  };
+}
+
+function startHostedResponseStreamHeartbeat<TChunk>(input: {
+  writer: HostedResponseStreamWriter<TChunk>;
+  heartbeat: HostedResponseStreamHeartbeat<TChunk>;
+}): { stop: () => void } {
+  const startedAt = Date.now();
+  let heartbeatCount = 0;
+  const interval = dntShim.setInterval(() => {
+    heartbeatCount += 1;
+    input.heartbeat.onBeat?.(getHeartbeatState(startedAt, heartbeatCount));
+
+    try {
+      input.writer.write(input.heartbeat.buildChunk());
+    } catch {
+      clearInterval(interval);
+    }
+  }, input.heartbeat.intervalMs ?? 15_000);
+
+  return {
+    stop: () => {
+      clearInterval(interval);
+      input.heartbeat.onStop?.(getHeartbeatState(startedAt, heartbeatCount));
+    },
+  };
+}
+
+export async function runHostedResponseStreamWithHeartbeat<TChunk>(
+  options: RunHostedResponseStreamWithHeartbeatOptions<TChunk>,
+): Promise<void> {
+  const heartbeat = options.heartbeat
+    ? startHostedResponseStreamHeartbeat({
+      writer: options.writer,
+      heartbeat: options.heartbeat,
+    })
+    : null;
+
+  try {
+    await runHostedLifecycle({
+      abortSignal: new AbortController().signal,
+      execution: options.execution,
+      adapter: {
+        startRun: () => ({ runId: options.runId ?? "response-stream" }),
+        appendEvents: (_run, chunk) => {
+          options.writer.write(chunk);
+        },
+      },
+      resolveTerminalState: () => ({ status: "completed" }),
+    });
+  } finally {
+    heartbeat?.stop();
+  }
+}

package/src/src/agent/index.ts

@@ -159,6 +159,7 @@ export {
   AgUiRuntimeMessageSchema,
   type AgUiRuntimeRequest,
   AgUiRuntimeRequestSchema,
+  normalizeAgUiBrowserRuntimeRequest,
   parseAgUiRuntimeRequest,
   parseAgUiRuntimeRequestOrError,
 } from "./runtime-ag-ui-contract.js";
@@ -173,6 +174,21 @@ export {
   finalizeAgUiBrowserEvents,
   mapRuntimeStreamEventToAgUiBrowserEvents,
 } from "./ag-ui-browser-encoder.js";
+export {
+  type AgUiRuntimeEventEncoder,
+  createAgUiRuntimeEventEncoder,
+  type CreateAgUiRuntimeEventEncoderOptions,
+} from "./ag-ui-runtime-event-encoder.js";
+export {
+  type AgUiBrowserFinalizeTracker,
+  createAgUiBrowserFinalizeTracker,
+  type CreateAgUiBrowserFinalizeTrackerOptions,
+} from "./ag-ui-browser-finalize-tracker.js";
+export {
+  type AgUiChunkEncoderBridge,
+  createAgUiChunkEncoderBridge,
+  type CreateAgUiChunkEncoderBridgeOptions,
+} from "./ag-ui-chunk-encoder-bridge.js";
 export {
   type AgUiBrowserResponseEncoder,
   type AgUiBrowserResponseExecution,
@@ -180,6 +196,14 @@ export {
   createAgUiBrowserResponseStream,
   type CreateAgUiBrowserResponseStreamInput,
 } from "./ag-ui-browser-response-stream.js";
+export {
+  createAgUiRuntimeBrowserResponse,
+  type CreateAgUiRuntimeBrowserResponseInput,
+} from "./ag-ui-runtime-browser-response.js";
+export {
+  createAgUiTrackedBrowserResponse,
+  type CreateAgUiTrackedBrowserResponseInput,
+} from "./ag-ui-tracked-browser-response.js";
 export {
   type ConversationRunContext,
   createConversationRunContext,
@@ -330,6 +354,12 @@ export {
   type HostedLifecycleTerminalState,
   runHostedLifecycle,
 } from "./hosted-lifecycle.js";
+export {
+  type HostedResponseStreamHeartbeat,
+  type HostedResponseStreamHeartbeatState,
+  type HostedResponseStreamWriter,
+  runHostedResponseStreamWithHeartbeat,
+} from "./hosted-response-stream.js";
 export {
   mergeToolCallInput,
   mergeToolInputDelta,
@@ -365,6 +395,7 @@ export {
   type AgUiSseEvent,
   createAgUiRunErrorEvent,
   createAgUiSseErrorResponse,
+  createAgUiSseResponse,
   normalizeAgUiMessages,
   parseAgUiRequest,
   parseAgUiRequestOrError,

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

@@ -9,6 +9,10 @@ const MAX_RUNTIME_MESSAGES = 100;
 
 const encoder = new TextEncoder();
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function isWithinJsonSizeLimit(value: unknown, maxBytes: number): boolean {
   try {
     return encoder.encode(JSON.stringify(value)).byteLength <= maxBytes;
@@ -143,6 +147,24 @@ export type AgUiRuntimeContextItem = z.infer<typeof AgUiRuntimeContextItemSchema
 export type AgUiRuntimeMessage = z.infer<typeof AgUiRuntimeMessageSchema>;
 export type AgUiRuntimeRequest = z.infer<typeof AgUiRuntimeRequestSchema>;
 
+export function normalizeAgUiBrowserRuntimeRequest(
+  input: AgUiRuntimeRequest,
+  defaults?: {
+    threadId?: string;
+    runId?: string;
+  },
+): AgUiRuntimeRequest {
+  const { state, ...rest } = input;
+
+  return {
+    ...rest,
+    threadId: defaults?.threadId ?? input.threadId,
+    runId: defaults?.runId ?? input.runId,
+    messages: input.messages,
+    ...(isRecord(state) ? { state } : {}),
+  };
+}
+
 export async function parseAgUiRuntimeRequest(request: Request): Promise<AgUiRuntimeRequest> {
   return AgUiRuntimeRequestSchema.parse(await request.json());
 }