veryfront 0.1.516 → 0.1.518

package/src/src/agent/hosted/ag-ui-chat-request.ts

@@ -0,0 +1,197 @@
+import { mapAgUiRuntimeMessagesToChatUiMessages } from "../../chat/ag-ui.js";
+import type { ChatRequestContext, ChatRuntimeOverrides } from "../../chat/types.js";
+import { defineSchema } from "../../schemas/index.js";
+import type { InferSchema } from "../../extensions/schema/index.js";
+import {
+  createAgUiRuntimeContextMap,
+  deriveAgUiForwardedConfig,
+  parseAgUiContextBoolean,
+  parseAgUiContextNullableString,
+  parseAgUiContextSchema,
+  parseAgUiContextString,
+} from "../ag-ui/forwarded-context.js";
+import type { AgUiRuntimeRequest } from "../runtime/ag-ui-contract.js";
+import { hostedChatRuntimeOverridesSchema } from "./chat-request.js";
+import type {
+  HostedChatProjectAccessResult,
+  ParsedHostedChatRequest,
+  ParseHostedChatRequestOptions,
+} from "./chat-request-parser.js";
+
+export const getHostedAgUiChatForwardedConfigSchema = defineSchema((v) =>
+  v.object({
+    projectId: v.string().nullable().optional(),
+    branchId: v.string().nullable().optional(),
+    conversationId: v.string().optional(),
+    environmentContext: v.string().optional(),
+    model: v.string().optional(),
+    allowDelegation: v.boolean().optional(),
+    runtimeOverrides: hostedChatRuntimeOverridesSchema.optional(),
+  })
+    .strict()
+);
+
+/** @deprecated Use getHostedAgUiChatForwardedConfigSchema() */
+export const hostedAgUiChatForwardedConfigSchema = getHostedAgUiChatForwardedConfigSchema();
+
+export type HostedAgUiChatForwardedConfig = InferSchema<
+  ReturnType<typeof getHostedAgUiChatForwardedConfigSchema>
+>;
+
+export type DerivedHostedAgUiChatContext = {
+  validatedContext: ChatRequestContext;
+  projectId: string | null;
+  conversationId: string | undefined;
+  model: string | undefined;
+  allowDelegation: boolean | undefined;
+  runtimeOverrides: ChatRuntimeOverrides | undefined;
+};
+
+export type ParsedHostedAgUiRequest = ParsedHostedChatRequest & {
+  agUiInput: AgUiRuntimeRequest;
+};
+
+export type BuildParsedHostedAgUiRequestOptions = {
+  agUiInput: AgUiRuntimeRequest;
+  authToken: string;
+  userId: string;
+  forwardedConfigNamespace?: string;
+  verifyProjectAccess?: ParseHostedChatRequestOptions["verifyProjectAccess"];
+};
+
+const getHostedValidationErrorBodySchema = defineSchema((v) =>
+  v.object({
+    error: v.string().optional(),
+    details: v.array(v.object({ message: v.string().optional() }).passthrough()).optional(),
+  })
+    .passthrough()
+);
+
+const hostedValidationErrorBodySchema = getHostedValidationErrorBodySchema();
+
+async function verifyHostedAgUiProjectAccess(input: {
+  projectId: string | null;
+  authToken: string;
+  verifyProjectAccess?: (
+    input: { projectId: string; authToken: string },
+  ) => Promise<HostedChatProjectAccessResult>;
+}): Promise<Response | undefined> {
+  if (!input.projectId || !input.verifyProjectAccess) {
+    return undefined;
+  }
+
+  const access = await input.verifyProjectAccess({
+    projectId: input.projectId,
+    authToken: input.authToken,
+  });
+  if (access.success) {
+    return undefined;
+  }
+
+  return Response.json(
+    { errorCode: access.error.errorCode, message: access.error.message },
+    { status: access.error.statusCode === 404 ? 404 : 403 },
+  );
+}
+
+export function deriveHostedAgUiChatContext(
+  agUiInput: AgUiRuntimeRequest,
+  options: { forwardedConfigNamespace?: string } = {},
+): DerivedHostedAgUiChatContext {
+  const contextMap = createAgUiRuntimeContextMap(agUiInput);
+  const contextNamespace = options.forwardedConfigNamespace ?? "veryfront";
+  const forwardedConfig = deriveAgUiForwardedConfig(agUiInput, {
+    schema: hostedAgUiChatForwardedConfigSchema,
+    namespace: options.forwardedConfigNamespace,
+  });
+
+  const projectId = forwardedConfig?.projectId ??
+    parseAgUiContextNullableString(contextMap.get(`${contextNamespace}.projectId`)) ?? null;
+  const branchId = forwardedConfig?.branchId ??
+    parseAgUiContextNullableString(contextMap.get(`${contextNamespace}.branchId`)) ?? null;
+  const environmentContext = forwardedConfig?.environmentContext ??
+    parseAgUiContextString(contextMap.get(`${contextNamespace}.environmentContext`));
+  const conversationId = forwardedConfig?.conversationId ??
+    parseAgUiContextString(contextMap.get(`${contextNamespace}.conversationId`));
+
+  const validatedContext: ChatRequestContext = {
+    projectId,
+    branchId,
+    ...(conversationId ? { conversationId } : {}),
+    ...(environmentContext ? { environmentContext } : {}),
+  };
+
+  return {
+    validatedContext,
+    projectId,
+    conversationId,
+    model: forwardedConfig?.model ??
+      parseAgUiContextString(contextMap.get(`${contextNamespace}.model`)),
+    allowDelegation: forwardedConfig?.allowDelegation ??
+      parseAgUiContextBoolean(contextMap.get(`${contextNamespace}.allowDelegation`)),
+    runtimeOverrides: forwardedConfig?.runtimeOverrides ??
+      parseAgUiContextSchema(
+        contextMap.get(`${contextNamespace}.runtimeOverrides`),
+        hostedChatRuntimeOverridesSchema,
+      ),
+  };
+}
+
+export async function createHostedAgUiValidationErrorResponse(
+  response: Response,
+): Promise<Response> {
+  const bodyResult = hostedValidationErrorBodySchema.safeParse(
+    await response.json().catch((): null => null),
+  );
+  const body = bodyResult.success ? bodyResult.data : null;
+
+  const detailMessage = body?.details
+    ?.map((detail) => detail.message)
+    .filter((message): message is string => typeof message === "string")
+    .join(", ") ||
+    body?.error ||
+    "Invalid AG-UI request";
+
+  return Response.json(
+    { errorCode: "VALIDATION_ERROR", message: `Invalid AG-UI request: ${detailMessage}` },
+    { status: 400 },
+  );
+}
+
+export async function buildParsedHostedAgUiRequest(
+  input: BuildParsedHostedAgUiRequestOptions,
+): Promise<ParsedHostedAgUiRequest | Response> {
+  const chatContext = deriveHostedAgUiChatContext(input.agUiInput, {
+    forwardedConfigNamespace: input.forwardedConfigNamespace,
+  });
+
+  const accessError = await verifyHostedAgUiProjectAccess({
+    projectId: chatContext.projectId,
+    authToken: input.authToken,
+    verifyProjectAccess: input.verifyProjectAccess,
+  });
+  if (accessError) {
+    return accessError;
+  }
+
+  return {
+    agentId: undefined,
+    agUiInput: input.agUiInput,
+    userId: input.userId,
+    authToken: input.authToken,
+    messages: mapAgUiRuntimeMessagesToChatUiMessages(input.agUiInput.messages),
+    validatedContext: chatContext.validatedContext,
+    projectId: chatContext.projectId,
+    conversationId: chatContext.conversationId,
+    parentRunId: input.agUiInput.parentRunId,
+    upstreamParentConversationId: undefined,
+    upstreamParentRunId: undefined,
+    spawnedFromToolCallId: undefined,
+    model: chatContext.model,
+    allowDelegation: chatContext.allowDelegation,
+    forwardedProps: input.agUiInput.forwardedProps,
+    runtimeOverrides: chatContext.runtimeOverrides,
+    durableRootRun: undefined,
+    persistLatestUserMessageBeforeDurableRun: true,
+  };
+}

package/src/src/agent/hosted/agent-project-steering.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import {
+  createHostedProjectSteeringAdapter,
+  type HostedProjectSkillIdsContext,
+  type HostedProjectSteeringAdapter,
+  type HostedProjectSteeringLogger,
+} from "./project-steering-adapter.js";
+import {
+  loadRuntimeAgentMarkdownDefinitionFromFile,
+  resolveRuntimeAgentDefinitionsDir,
+  resolveRuntimeAgentMarkdownDefinitionFilePath,
+} from "../runtime/agent-definition-files.js";
+import type { RuntimeAgentMarkdownDefinition } from "../runtime/agent-definition.js";
+import { resolveRuntimeBuiltinSkillsDir } from "../runtime/builtin-skill-files.js";
+import type {
+  RuntimeProjectFilesFetch,
+  RuntimeProjectFilesTrace,
+} from "../runtime/project-files-client.js";
+import type { RuntimeProjectSteeringLookup } from "../runtime/project-skill-catalog.js";
+import type { RuntimeLoadSkillToolContext } from "../runtime/load-skill-tool.js";
+import type { RuntimeSkillDefinition } from "../runtime/skill-metadata.js";
+
+const runtimeAgentFileIdSchema = z.string().min(1).regex(/^[A-Za-z0-9._-]+$/);
+const runtimeAgentDefinitionFileNameSchema = z.string().min(1).regex(/^[A-Za-z0-9._-]+\.md$/);
+
+export const hostedAgentProjectSteeringOptionsSchema = z.object({
+  baseDir: z.string().min(1),
+  agentId: runtimeAgentFileIdSchema,
+  fileName: runtimeAgentDefinitionFileNameSchema.optional(),
+  skillsDir: z.string().min(1).optional(),
+});
+
+export type HostedAgentProjectSteeringOptionsData = z.infer<
+  typeof hostedAgentProjectSteeringOptionsSchema
+>;
+
+export type HostedAgentProjectSteeringLogger = HostedProjectSteeringLogger & {
+  error?: (message: string, metadata?: Record<string, unknown>) => void;
+};
+
+export type HostedAgentProjectSteeringOptions = HostedAgentProjectSteeringOptionsData & {
+  getApiUrl: () => string | URL;
+  logger?: HostedAgentProjectSteeringLogger;
+  trace?: RuntimeProjectFilesTrace;
+  fetch?: RuntimeProjectFilesFetch;
+};
+
+export type HostedAgentProjectSteering = {
+  getAgentConfig: () => RuntimeAgentMarkdownDefinition;
+  getProjectInstructions: (lookup: RuntimeProjectSteeringLookup) => Promise<string>;
+  getSkillsConfig: (lookup: RuntimeProjectSteeringLookup) => Promise<RuntimeSkillDefinition[]>;
+  createLoadSkillTool: (
+    context: RuntimeLoadSkillToolContext,
+  ) => ReturnType<HostedProjectSteeringAdapter["createLoadSkillTool"]>;
+  refreshProjectSkillIds: (context: HostedProjectSkillIdsContext) => Promise<void>;
+  getProjectSteeringAdapter: () => HostedProjectSteeringAdapter;
+};
+
+function stringifyError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function createHostedAgentProjectSteering(
+  options: HostedAgentProjectSteeringOptions,
+): HostedAgentProjectSteering {
+  const parsedOptions = hostedAgentProjectSteeringOptionsSchema.parse(options);
+  const agentsDir = resolveRuntimeAgentDefinitionsDir({
+    baseDir: parsedOptions.baseDir,
+    id: parsedOptions.agentId,
+    fileName: parsedOptions.fileName,
+  });
+  const agentFilePath = resolveRuntimeAgentMarkdownDefinitionFilePath({
+    agentsDir,
+    id: parsedOptions.agentId,
+    fileName: parsedOptions.fileName,
+  });
+  const skillsDir = parsedOptions.skillsDir ??
+    resolveRuntimeBuiltinSkillsDir(parsedOptions.baseDir);
+
+  let cachedAgentConfig: RuntimeAgentMarkdownDefinition | null = null;
+  let cachedProjectSteeringAdapter: HostedProjectSteeringAdapter | null = null;
+
+  function getAgentConfig(): RuntimeAgentMarkdownDefinition {
+    if (cachedAgentConfig) {
+      return cachedAgentConfig;
+    }
+
+    try {
+      cachedAgentConfig = loadRuntimeAgentMarkdownDefinitionFromFile({
+        agentsDir,
+        id: parsedOptions.agentId,
+        fileName: parsedOptions.fileName,
+      });
+      return cachedAgentConfig;
+    } catch (error) {
+      options.logger?.error?.("Failed to load agent config", {
+        error: stringifyError(error),
+        filePath: agentFilePath,
+      });
+      throw error;
+    }
+  }
+
+  function getProjectSteeringAdapter(): HostedProjectSteeringAdapter {
+    if (cachedProjectSteeringAdapter) {
+      return cachedProjectSteeringAdapter;
+    }
+
+    cachedProjectSteeringAdapter = createHostedProjectSteeringAdapter({
+      apiUrl: options.getApiUrl(),
+      skillsDir,
+      logger: options.logger,
+      trace: options.trace,
+      fetch: options.fetch,
+    });
+
+    return cachedProjectSteeringAdapter;
+  }
+
+  return {
+    getAgentConfig,
+    getProjectSteeringAdapter,
+    getProjectInstructions: (lookup) => getProjectSteeringAdapter().getProjectInstructions(lookup),
+    getSkillsConfig: (lookup) => getProjectSteeringAdapter().getSkillsConfig(lookup),
+    createLoadSkillTool: (context) => getProjectSteeringAdapter().createLoadSkillTool(context),
+    refreshProjectSkillIds: (context) =>
+      getProjectSteeringAdapter().refreshProjectSkillIds(context),
+  };
+}

package/src/src/agent/hosted/agent-run-lifecycle.ts

@@ -0,0 +1,161 @@
+import type { ConversationRunChunkMirror } from "../conversation/run-chunk-mirror.js";
+import {
+  type ConversationHostedTerminalAdapter,
+  createConversationHostedTerminalAdapter,
+} from "../conversation/hosted-terminal.js";
+import type { HostedChatExecutionLifecycleAdapter } from "./chat-execution-runtime.js";
+import type { HostedLifecycleTerminalState } from "./lifecycle.js";
+import type { HostedConversationRootRunState } from "../conversation/root-run-lifecycle.js";
+import {
+  type AgentTraceAttributes,
+  buildAgentRunTraceAttributes,
+  buildFinalizedAgentRunTraceAttributes,
+} from "../agent-trace-attributes.js";
+
+export interface HostedAgentRunSpan {
+  setAttributes: (attributes: AgentTraceAttributes) => void;
+  finish: () => void;
+  withContext: <T>(fn: () => T) => T;
+}
+
+export interface HostedAgentRunTracer {
+  startSpan: (name: string) => HostedAgentRunSpan;
+}
+
+export interface HostedAgentRunSpanFinalState {
+  status: "completed" | "failed" | "cancelled";
+  modelId?: string | null;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+  };
+  terminalErrorCode?: string | null;
+  terminalErrorMessage?: string | null;
+}
+
+export interface HostedAgentRunSpanController {
+  withContext: <T>(fn: () => T) => T;
+  setAttributes: (attributes: AgentTraceAttributes) => void;
+  setMessageId: (messageId: string) => void;
+  finalize: (finalState: HostedAgentRunSpanFinalState) => void;
+}
+
+export interface CreateHostedAgentRunSpanControllerInput {
+  tracer: HostedAgentRunTracer;
+  spanName?: string;
+  operationName: "chat" | "invoke_agent";
+  conversationId?: string;
+  projectId: string | null;
+  userId: string;
+  agentId: string;
+  rootRun?: Pick<HostedConversationRootRunState, "runId" | "messageId"> | null;
+  upstreamParentConversationId?: string;
+  upstreamParentRunId?: string;
+  spawnedFromToolCallId?: string;
+}
+
+export function createHostedAgentRunSpanController(
+  input: CreateHostedAgentRunSpanControllerInput,
+): HostedAgentRunSpanController {
+  const span = input.tracer.startSpan(input.spanName ?? "agent.run");
+  let finalized = false;
+
+  span.setAttributes(
+    buildAgentRunTraceAttributes({
+      operationName: input.operationName,
+      conversationId: input.conversationId,
+      projectId: input.projectId,
+      userId: input.userId,
+      agentId: input.agentId,
+      runId: input.rootRun?.runId,
+      parentConversationId: input.upstreamParentConversationId,
+      parentRunId: input.upstreamParentRunId,
+      messageId: input.rootRun?.messageId,
+      toolCallId: input.spawnedFromToolCallId,
+    }),
+  );
+
+  return {
+    withContext: (fn) => span.withContext(fn),
+    setAttributes: (attributes) => {
+      span.setAttributes(attributes);
+    },
+    setMessageId: (messageId) => {
+      span.setAttributes({ "message.id": messageId });
+    },
+    finalize: (finalState) => {
+      if (finalized) {
+        return;
+      }
+
+      finalized = true;
+      span.setAttributes(buildFinalizedAgentRunTraceAttributes(finalState));
+      span.finish();
+    },
+  };
+}
+
+export interface HostedRootRunLifecycleRuntimeAdapter extends HostedChatExecutionLifecycleAdapter {
+  durableRootRun: HostedConversationRootRunState | null;
+  durableRunMirror: ConversationRunChunkMirror | null;
+}
+
+export interface CreateHostedRootRunLifecycleRuntimeAdapterInput {
+  authToken: string;
+  apiUrl: string;
+  modelId: string;
+  durableRootRun: HostedConversationRootRunState | null;
+  durableRunMirror: ConversationRunChunkMirror | null;
+  agentRunSpan: Pick<HostedAgentRunSpanController, "finalize">;
+  resolveProvider: (modelId: string) => string;
+  createTerminalAdapter?: (
+    input: Parameters<typeof createConversationHostedTerminalAdapter>[0],
+  ) => ConversationHostedTerminalAdapter;
+}
+
+function finalizeHostedAgentRunSpan(input: {
+  agentRunSpan: Pick<HostedAgentRunSpanController, "finalize">;
+  modelId: string;
+  terminalState: HostedLifecycleTerminalState;
+}): void {
+  input.agentRunSpan.finalize({
+    status: input.terminalState.status,
+    modelId: input.terminalState.metadata?.modelId ?? input.modelId,
+    usage: input.terminalState.metadata?.usage,
+    terminalErrorCode: input.terminalState.terminalErrorCode,
+    terminalErrorMessage: input.terminalState.terminalErrorMessage,
+  });
+}
+
+export function createHostedRootRunLifecycleRuntimeAdapter(
+  input: CreateHostedRootRunLifecycleRuntimeAdapterInput,
+): HostedRootRunLifecycleRuntimeAdapter {
+  const createTerminal = input.createTerminalAdapter ?? createConversationHostedTerminalAdapter;
+
+  return {
+    durableRootRun: input.durableRootRun,
+    durableRunMirror: input.durableRunMirror,
+    terminal: createTerminal({
+      authToken: input.authToken,
+      apiUrl: input.apiUrl,
+      run: input.durableRootRun
+        ? {
+          ...input.durableRootRun,
+          waitingToolCallId: null,
+          waitingToolName: null,
+          status: "running",
+        }
+        : null,
+      fallbackModelId: input.modelId,
+      resolveProvider: input.resolveProvider,
+      onTerminalState: (terminalState) => {
+        finalizeHostedAgentRunSpan({
+          agentRunSpan: input.agentRunSpan,
+          modelId: input.modelId,
+          terminalState,
+        });
+      },
+    }),
+  };
+}