Protect Server Call

Add Vela at the server boundary where model execution actually happens, not in UI components. The standard sequence is environment diagnostics, scope resolution, prepare, non-allow return, allow-only model call, and reporting.

Framework-Agnostic Flow

import {
  createOpenAiCompatibleUsageReportInput,
  createVelaClientFromEnvironment,
  createVelaEnvironmentDiagnosticsResponse,
  createVelaErrorResponse,
  createVelaIntegration,
  getVelaEnvironmentDiagnostics,
  resolveVelaExecutionScope,
} from "@vel4ai/sdk";

declare const process: { env: Record<string, string | undefined> };
declare function callOpenAiCompatible(input: {
  model: string;
  apiKey: string;
  baseURL: string;
  messages: unknown[];
}): Promise<{ usage?: unknown; body: unknown }>;

export async function POST(req: Request): Promise<Response> {
  const environment = getVelaEnvironmentDiagnostics({ env: process.env });

  if (!environment.ok) {
    return createVelaEnvironmentDiagnosticsResponse(environment);
  }

  try {
    const body = (await req.json()) as { vela?: unknown; messages?: unknown[] };
    const executionScope = resolveVelaExecutionScope(body.vela);

    if (!executionScope) {
      return Response.json({ error: "Vela execution scope is missing." }, { status: 400 });
    }

    const vela = createVelaIntegration({
      client: createVelaClientFromEnvironment({ env: process.env }),
      executionScope,
    });
    const prepared = await vela.prepareExecutionWithResponse({
      estimatedCostUsd: 0.05,
    });

    if (prepared.outcome !== "allow") {
      return prepared.response;
    }

    const result = await callOpenAiCompatible({
      model: prepared.openAiCompatibleModel,
      ...prepared.openAiCompatibleClientOptions,
      messages: body.messages ?? [],
    });

    await prepared.reportCompletedWithUsage(
      createOpenAiCompatibleUsageReportInput(result.usage),
    );

    return Response.json(result.body);
  } catch (error) {
    return createVelaErrorResponse(error, {
      fallbackMessage: "Model execution failed.",
    });
  }
}

App Concerns That Stay In The App

• Conversation history, prompts, tools, and attachments.
• UI state, retries, and rate limit display.
• Workspace / tenant mapping.
• App logs and trace IDs.

Vela does not take these over. It is responsible only for execution permission, relay access, and audit reporting.