veryfront 0.1.231 → 0.1.233

package/src/src/agent/durable.ts

@@ -0,0 +1,259 @@
+import "../../_dnt.polyfills.js";
+import * as dntShim from "../../_dnt.shims.js";
+import { z } from "zod";
+
+const AGENT_RUN_API_TIMEOUT_MS = 15_000;
+
+export const ConversationRunTargetsSchema = z.object({
+  sourceTargetKind: z.enum(["project", "preview_branch"]).nullable(),
+  runtimeTargetKind: z.enum(["production", "preview_branch"]).nullable(),
+  targetBranchId: z.string().uuid().nullable(),
+});
+
+export type ConversationRunTargets = z.infer<typeof ConversationRunTargetsSchema>;
+
+export function resolveConversationRunTargets(input: {
+  projectId?: string | null;
+  branchId?: string | null;
+}): ConversationRunTargets {
+  return ConversationRunTargetsSchema.parse(
+    !input.projectId
+      ? {
+        sourceTargetKind: null,
+        runtimeTargetKind: null,
+        targetBranchId: null,
+      }
+      : input.branchId
+      ? {
+        sourceTargetKind: "preview_branch",
+        runtimeTargetKind: "preview_branch",
+        targetBranchId: input.branchId,
+      }
+      : {
+        sourceTargetKind: "project",
+        runtimeTargetKind: "production",
+        targetBranchId: null,
+      },
+  );
+}
+
+export const ConversationRunProjectionSchema = z
+  .object({
+    runId: z.string().min(1).optional(),
+    run_id: z.string().min(1).optional(),
+    conversationId: z.string().uuid().optional(),
+    conversation_id: z.string().uuid().optional(),
+    messageId: z.string().uuid().optional(),
+    message_id: z.string().uuid().optional(),
+    latestEventId: z.number().int().nonnegative().optional(),
+    latest_event_id: z.number().int().nonnegative().optional(),
+    latestExternalEventSequence: z.number().int().nonnegative().optional(),
+    latest_external_event_sequence: z.number().int().nonnegative().optional(),
+    status: z.enum(["pending", "running", "waiting_for_tool", "completed", "failed", "cancelled"]),
+  })
+  .passthrough()
+  .transform((data) => {
+    const runId = data.runId ?? data.run_id;
+    const conversationId = data.conversationId ?? data.conversation_id;
+    const messageId = data.messageId ?? data.message_id;
+    const latestEventId = data.latestEventId ?? data.latest_event_id ?? 0;
+    const latestExternalEventSequence = data.latestExternalEventSequence ??
+      data.latest_external_event_sequence;
+
+    if (!runId || !conversationId || !messageId) {
+      throw new Error("Missing run identifiers in durable run response");
+    }
+
+    if (latestExternalEventSequence === undefined) {
+      throw new Error("Missing latestExternalEventSequence in durable run response");
+    }
+
+    return {
+      runId,
+      conversationId,
+      messageId,
+      latestEventId,
+      latestExternalEventSequence,
+      status: data.status,
+    };
+  });
+
+export type ConversationRunProjection = z.infer<typeof ConversationRunProjectionSchema>;
+
+export const CreateConversationRunAcceptedSchema = z
+  .object({
+    run: z
+      .object({
+        runId: z.string().min(1).optional(),
+        run_id: z.string().min(1).optional(),
+      })
+      .passthrough(),
+  })
+  .passthrough()
+  .transform((data) => {
+    const runId = data.run.runId ?? data.run.run_id;
+    if (!runId) {
+      throw new Error("Missing run id in canonical create run response");
+    }
+
+    return { runId };
+  });
+
+export const CompleteConversationRunResponseSchema = z
+  .object({
+    completed: z.boolean(),
+    run: z
+      .object({
+        runId: z.string().min(1).optional(),
+        run_id: z.string().min(1).optional(),
+        status: z.enum(["pending", "running", "waiting", "completed", "failed", "cancelled"]),
+      })
+      .passthrough(),
+  })
+  .passthrough();
+
+export interface ConversationAgentRunUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+}
+
+export interface CreateConversationAgentRunInput {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId?: string;
+  agentId: string;
+  projectId?: string | null;
+  branchId?: string | null;
+}
+
+export interface FinalizeConversationAgentRunInput {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId: string;
+  status: "completed" | "failed" | "cancelled";
+  model: string;
+  provider: string;
+  usage?: ConversationAgentRunUsage;
+  terminalErrorCode?: string | null;
+  terminalErrorMessage?: string | null;
+}
+
+async function controlPlaneJson<T>(input: {
+  authToken: string;
+  url: string;
+  method?: "GET" | "POST";
+  body?: unknown;
+  responseSchema: z.ZodSchema<T>;
+  operation: string;
+}): Promise<T> {
+  const controller = new AbortController();
+  const timeout = dntShim.setTimeout(() => {
+    controller.abort();
+  }, AGENT_RUN_API_TIMEOUT_MS);
+
+  let response: Response;
+  try {
+    response = await fetch(input.url, {
+      method: input.method ?? "GET",
+      headers: {
+        Authorization: `Bearer ${input.authToken}`,
+        "Content-Type": "application/json",
+      },
+      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+      throw new Error(`${input.operation} timed out after ${AGENT_RUN_API_TIMEOUT_MS}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `${input.operation} failed (${response.status}): ${body || response.statusText}`,
+    );
+  }
+
+  return input.responseSchema.parse(await response.json());
+}
+
+export async function createConversationAgentRun(
+  input: CreateConversationAgentRunInput,
+): Promise<ConversationRunProjection> {
+  const targets = resolveConversationRunTargets({
+    projectId: input.projectId ?? null,
+    branchId: input.branchId ?? null,
+  });
+  const runId = input.runId ?? `run_${dntShim.crypto.randomUUID()}`;
+
+  await controlPlaneJson({
+    authToken: input.authToken,
+    url: `${input.apiUrl}/runs`,
+    method: "POST",
+    body: {
+      kind: "agent",
+      owner: {
+        kind: "conversation",
+        id: input.conversationId,
+      },
+      public_id: runId,
+      request: {
+        mode: "default_chat",
+        agent_id: input.agentId,
+        initial_status: "running",
+        ...(targets.sourceTargetKind ? { source_target_kind: targets.sourceTargetKind } : {}),
+        ...(targets.runtimeTargetKind ? { runtime_target_kind: targets.runtimeTargetKind } : {}),
+        ...(targets.targetBranchId
+          ? {
+            source_target_branch_id: targets.targetBranchId,
+            runtime_target_branch_id: targets.targetBranchId,
+          }
+          : {}),
+      },
+    },
+    responseSchema: CreateConversationRunAcceptedSchema,
+    operation: "Create canonical durable run",
+  });
+
+  return controlPlaneJson({
+    authToken: input.authToken,
+    url: `${input.apiUrl}/conversations/${input.conversationId}/runs/${runId}`,
+    responseSchema: ConversationRunProjectionSchema,
+    operation: "Read conversation durable run projection",
+  });
+}
+
+export async function finalizeConversationAgentRun(
+  input: FinalizeConversationAgentRunInput,
+): Promise<void> {
+  const metadata = input.status === "completed"
+    ? {
+      provider: input.provider,
+      model: input.model,
+      inputTokens: input.usage?.inputTokens ?? 0,
+      outputTokens: input.usage?.outputTokens ?? 0,
+      finishReason: "stop",
+    }
+    : null;
+
+  await controlPlaneJson({
+    authToken: input.authToken,
+    url: `${input.apiUrl}/runs/${input.runId}/complete`,
+    method: "POST",
+    body: {
+      status: input.status,
+      metadata,
+      terminal_error_code: input.terminalErrorCode ?? null,
+      terminal_error_message: input.terminalErrorMessage ?? null,
+    },
+    responseSchema: CompleteConversationRunResponseSchema,
+    operation: "Complete canonical durable run",
+  });
+}

package/src/src/agent/index.ts

@@ -180,6 +180,29 @@ export {
   createAgUiBrowserResponseStream,
   type CreateAgUiBrowserResponseStreamInput,
 } from "./ag-ui-browser-response-stream.js";
+export {
+  bootstrapConversationAgentRun,
+  type BootstrapConversationAgentRunResult,
+  type ConversationMessageRecord,
+  ConversationMessageRecordSchema,
+  type ConversationRecord,
+  ConversationRecordSchema,
+  createConversationMessage,
+  createConversationRecord,
+  ensureConversationProjectLink,
+  fetchConversationRecord,
+} from "./conversation-bootstrap.js";
+export {
+  CompleteConversationRunResponseSchema,
+  type ConversationAgentRunUsage,
+  type ConversationRunProjection,
+  ConversationRunProjectionSchema,
+  type ConversationRunTargets,
+  ConversationRunTargetsSchema,
+  createConversationAgentRun,
+  finalizeConversationAgentRun,
+  resolveConversationRunTargets,
+} from "./durable.js";
 export {
   type HostedChildLifecycleAdapter,
   type HostedChildLifecycleRunnerOptions,

package/src/src/channels/control-plane.ts

@@ -8,6 +8,13 @@ import { z } from "zod";
 
 const SIGNATURE_SKEW_SECONDS = 5;
 
+export const CONTROL_PLANE_AGENTS_LIST_PATH = "/api/control-plane/agents/list";
+export const CONTROL_PLANE_AGENT_STREAM_PATH = "/api/control-plane/agents/stream";
+export const CONTROL_PLANE_AGENT_RUNS_PATH_PREFIX = "/api/control-plane/agents/runs/";
+export const LEGACY_INTERNAL_AGENTS_LIST_PATH = "/internal/agents/list";
+export const LEGACY_INTERNAL_AGENT_STREAM_PATH = "/internal/agents/stream";
+export const LEGACY_INTERNAL_AGENT_RUNS_PATH_PREFIX = "/internal/agents/runs/";
+
 const compactJwsHeaderSchema = z.object({
   alg: z.literal("EdDSA"),
   typ: z.string().optional(),

package/src/src/proxy/handler.ts

@@ -70,6 +70,7 @@ const INTERNAL_CONTROL_PLANE_SIGNATURE_HEADERS = [
 
 function isInternalControlPlanePath(pathname: string): boolean {
   return pathname === "/channels/invoke" ||
+    pathname.startsWith("/api/control-plane/agents/") ||
     pathname.startsWith("/internal/agents/") ||
     pathname.startsWith("/internal/tasks/") ||
     pathname.startsWith("/internal/workflows/");

package/src/src/server/handlers/request/agent-run-cancel.handler.ts

@@ -1,3 +1,7 @@
+import {
+  CONTROL_PLANE_AGENT_RUNS_PATH_PREFIX,
+  LEGACY_INTERNAL_AGENT_RUNS_PATH_PREFIX,
+} from "../../../channels/control-plane.js";
 import {
   ControlPlaneRequestError,
   verifyControlPlaneRequest,
@@ -15,7 +19,7 @@ import { BaseHandler } from "../response/base.js";
 import type { HandlerContext, HandlerMetadata, HandlerPriority, HandlerResult } from "../types.js";
 import { PRIORITY_MEDIUM_API } from "../../../utils/constants/index.js";
 
-const CANCEL_PATH_REGEX = /^\/internal\/agents\/runs\/([^/]+)$/;
+const CANCEL_PATH_REGEX = /^\/(?:api\/control-plane\/agents|internal\/agents)\/runs\/([^/]+)$/;
 
 function getRunId(pathname: string): string | null {
   return CANCEL_PATH_REGEX.exec(pathname)?.[1] ?? null;
@@ -25,7 +29,10 @@ export class AgentRunCancelHandler extends BaseHandler {
   metadata: HandlerMetadata = {
     name: "AgentRunCancelHandler",
     priority: PRIORITY_MEDIUM_API as HandlerPriority,
-    patterns: [{ pattern: "/internal/agents/runs/", prefix: true, method: "DELETE" }],
+    patterns: [
+      { pattern: CONTROL_PLANE_AGENT_RUNS_PATH_PREFIX, prefix: true, method: "DELETE" },
+      { pattern: LEGACY_INTERNAL_AGENT_RUNS_PATH_PREFIX, prefix: true, method: "DELETE" },
+    ],
   };
 
   constructor(private readonly sessionManager: AgentRunSessionManager = agentRunSessionManager) {

package/src/src/server/handlers/request/agent-run-resume.handler.ts

@@ -1,3 +1,7 @@
+import {
+  CONTROL_PLANE_AGENT_RUNS_PATH_PREFIX,
+  LEGACY_INTERNAL_AGENT_RUNS_PATH_PREFIX,
+} from "../../../channels/control-plane.js";
 import {
   ControlPlaneRequestError,
   verifyControlPlaneRequest,
@@ -19,7 +23,8 @@ import { BaseHandler } from "../response/base.js";
 import type { HandlerContext, HandlerMetadata, HandlerPriority, HandlerResult } from "../types.js";
 import { PRIORITY_MEDIUM_API } from "../../../utils/constants/index.js";
 
-const RESUME_PATH_REGEX = /^\/internal\/agents\/runs\/([^/]+)\/resume$/;
+const RESUME_PATH_REGEX =
+  /^\/(?:api\/control-plane\/agents|internal\/agents)\/runs\/([^/]+)\/resume$/;
 
 function getRunId(pathname: string): string | null {
   return RESUME_PATH_REGEX.exec(pathname)?.[1] ?? null;
@@ -29,7 +34,10 @@ export class AgentRunResumeHandler extends BaseHandler {
   metadata: HandlerMetadata = {
     name: "AgentRunResumeHandler",
     priority: PRIORITY_MEDIUM_API as HandlerPriority,
-    patterns: [{ pattern: "/internal/agents/runs/", prefix: true, method: "POST" }],
+    patterns: [
+      { pattern: CONTROL_PLANE_AGENT_RUNS_PATH_PREFIX, prefix: true, method: "POST" },
+      { pattern: LEGACY_INTERNAL_AGENT_RUNS_PATH_PREFIX, prefix: true, method: "POST" },
+    ],
   };
 
   constructor(private readonly sessionManager: AgentRunSessionManager = agentRunSessionManager) {

package/src/src/server/handlers/request/agent-stream.handler.ts

@@ -1,6 +1,10 @@
 import type { Agent } from "../../../agent/index.js";
 import { defaultChannelInvokeDeps } from "../../../channels/invoke.js";
-import { type RuntimeAgentDiscoveryDeps } from "../../../channels/control-plane.js";
+import {
+  CONTROL_PLANE_AGENT_STREAM_PATH,
+  LEGACY_INTERNAL_AGENT_STREAM_PATH,
+  type RuntimeAgentDiscoveryDeps,
+} from "../../../channels/control-plane.js";
 import {
   createRuntimeAgentStreamResponse,
   type RuntimeAgentStreamExecutionDeps,
@@ -116,7 +120,10 @@ export class AgentStreamHandler extends BaseHandler {
   metadata: HandlerMetadata = {
     name: "AgentStreamHandler",
     priority: PRIORITY_MEDIUM_API as HandlerPriority,
-    patterns: [{ pattern: "/internal/agents/stream", exact: true, method: "POST" }],
+    patterns: [
+      { pattern: CONTROL_PLANE_AGENT_STREAM_PATH, exact: true, method: "POST" },
+      { pattern: LEGACY_INTERNAL_AGENT_STREAM_PATH, exact: true, method: "POST" },
+    ],
   };
 
   constructor(private readonly deps: AgentStreamHandlerDeps = defaultDeps) {

package/src/src/server/handlers/request/internal-agents-list.handler.ts

@@ -1,8 +1,10 @@
 import { BaseHandler } from "../response/base.js";
 import type { HandlerContext, HandlerMetadata, HandlerPriority, HandlerResult } from "../types.js";
 import {
+  CONTROL_PLANE_AGENTS_LIST_PATH,
   type ControlPlaneAgentsListRequest,
   ControlPlaneAgentsListRequestSchema,
+  LEGACY_INTERNAL_AGENTS_LIST_PATH,
   listRuntimeAgents,
   type RuntimeAgentDiscoveryDeps,
 } from "../../../channels/control-plane.js";
@@ -23,7 +25,10 @@ export class InternalAgentsListHandler extends BaseHandler {
   metadata: HandlerMetadata = {
     name: "InternalAgentsListHandler",
     priority: PRIORITY_MEDIUM_API as HandlerPriority,
-    patterns: [{ pattern: "/internal/agents/list", exact: true, method: "POST" }],
+    patterns: [
+      { pattern: CONTROL_PLANE_AGENTS_LIST_PATH, exact: true, method: "POST" },
+      { pattern: LEGACY_INTERNAL_AGENTS_LIST_PATH, exact: true, method: "POST" },
+    ],
   };
 
   constructor(private readonly deps: RuntimeAgentDiscoveryDeps = defaultChannelInvokeDeps) {

package/src/src/server/runtime-handler/environment-resolution.ts

@@ -64,7 +64,8 @@ export function resolveEnvironment(
 
   // Some internal framework surfaces are routed directly to a runtime owner pod and
   // rely on signed control-plane auth instead of a user-facing release address.
-  const isInternalAgentControlPlanePath = opts.pathname.startsWith("/internal/agents/");
+  const isInternalAgentControlPlanePath = opts.pathname.startsWith("/internal/agents/") ||
+    opts.pathname.startsWith("/api/control-plane/agents/");
 
   // Skip releaseId validation for development assets and signed internal control-plane
   // requests because they do not require a user-facing release context.

package/src/src/server/runtime-handler/request-utils.ts

@@ -84,5 +84,6 @@ export function isWebSocketPath(pathname: string): boolean {
  * render cache prefix/content-source derivation and the enriched render payload.
  */
 export function shouldSkipEnrichedContext(pathname: string): boolean {
-  return pathname.startsWith("/api/") || pathname.startsWith("/internal/agents/");
+  return pathname.startsWith("/api/") || pathname.startsWith("/internal/agents/") ||
+    pathname.startsWith("/api/control-plane/agents/");
 }

package/src/src/utils/index.ts

@@ -24,15 +24,18 @@ export {
 } from "./runtime-guards.js";
 
 export {
+  __registerTraceContextGetter,
+  __registerTraceContextGetter as registerTraceContextGetter,
   agentLogger,
   bundlerLogger,
   createJobUserLogger,
   logger,
   refreshLoggerConfig,
   rendererLogger,
+  runWithRequestContextAsync,
   serverLogger,
 } from "./logger/index.js";
-export type { Logger } from "./logger/index.js";
+export type { Logger, RequestContext } from "./logger/index.js";
 
 export {
   BREAKPOINT_LG,

package/src/src/utils/logger/logger.ts

@@ -66,6 +66,12 @@ export interface LogEntry {
   task?: string;
   event_kind?: string;
   user_visible?: string;
+  user_id?: string;
+  conversation_id?: string;
+  /** @deprecated Use `user_id` instead. Kept for Grafana dashboard transition. */
+  userId?: string;
+  /** @deprecated Use `conversation_id` instead. Kept for Grafana dashboard transition. */
+  conversationId?: string;
   // Duration for timed operations
   /** @deprecated Use `duration_ms` instead. Kept for Grafana dashboard transition. Planned removal after Grafana dashboard migration is complete. */
   durationMs?: number;
@@ -327,6 +333,12 @@ class ConsoleLogger implements Logger {
     extractToEntryField(entry, mergedContext, "event_kind", (v) => String(v));
     extractToEntryField(entry, mergedContext, "user_visible", (v) => String(v));
     extractToEntryField(entry, mergedContext, "duration_ms", (v) => Number(v));
+    extractToEntryField(entry, mergedContext, "user_id", (v) => String(v));
+    extractToEntryField(entry, mergedContext, "conversation_id", (v) => String(v));
+
+    // Also extract camelCase variants so callers can use either convention
+    extractToEntryField(entry, mergedContext, "userId", (v) => String(v));
+    extractToEntryField(entry, mergedContext, "conversationId", (v) => String(v));
 
     // Emit snake_case aliases for camelCase fields (transition period)
     if (entry.requestId && !entry.request_id) entry.request_id = entry.requestId;
@@ -334,6 +346,10 @@ class ConsoleLogger implements Logger {
     if (entry.spanId && !entry.span_id) entry.span_id = entry.spanId;
     if (entry.projectSlug && !entry.project_slug) entry.project_slug = entry.projectSlug;
     if (entry.durationMs != null && entry.duration_ms == null) entry.duration_ms = entry.durationMs;
+    if (entry.userId && !entry.user_id) entry.user_id = entry.userId;
+    if (entry.conversationId && !entry.conversation_id) {
+      entry.conversation_id = entry.conversationId;
+    }
 
     if (Object.keys(mergedContext).length > 0) entry.context = mergedContext;
     if (error) entry.error = error;

package/src/src/utils/logger/request-context.ts

@@ -16,6 +16,8 @@ export interface RequestContext {
   projectSlug?: string;
   projectId?: string;
   domain?: string;
+  userId?: string;
+  conversationId?: string;
 }
 
 export const requestContextStore = new AsyncLocalStorage<RequestContext>();

package/src/src/utils/version-constant.ts

@@ -1,3 +1,3 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
-export const VERSION = "0.1.231";
+export const VERSION = "0.1.233";