veryfront 0.1.233 → 0.1.235

package/src/src/agent/durable.ts

@@ -4,6 +4,34 @@ import { z } from "zod";
 
 const AGENT_RUN_API_TIMEOUT_MS = 15_000;
 
+function createTimedAbortSignal(timeoutMs: number, abortSignal?: AbortSignal) {
+  const controller = new AbortController();
+  let abortedByCaller = false;
+  const timeout = dntShim.setTimeout(() => {
+    controller.abort();
+  }, timeoutMs);
+
+  const onAbort = () => {
+    abortedByCaller = true;
+    controller.abort();
+  };
+
+  if (abortSignal?.aborted) {
+    onAbort();
+  } else {
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+  }
+
+  return {
+    signal: controller.signal,
+    wasAbortedByCaller: () => abortedByCaller,
+    cleanup: () => {
+      clearTimeout(timeout);
+      abortSignal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
 export const ConversationRunTargetsSchema = z.object({
   sourceTargetKind: z.enum(["project", "preview_branch"]).nullable(),
   runtimeTargetKind: z.enum(["production", "preview_branch"]).nullable(),
@@ -37,6 +65,15 @@ export function resolveConversationRunTargets(input: {
   );
 }
 
+export const ConversationRunStatusSchema = z.enum([
+  "pending",
+  "running",
+  "waiting_for_tool",
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
 export const ConversationRunProjectionSchema = z
   .object({
     runId: z.string().min(1).optional(),
@@ -49,7 +86,7 @@ export const ConversationRunProjectionSchema = z
     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"]),
+    status: ConversationRunStatusSchema,
   })
   .passthrough()
   .transform((data) => {
@@ -79,6 +116,14 @@ export const ConversationRunProjectionSchema = z
   });
 
 export type ConversationRunProjection = z.infer<typeof ConversationRunProjectionSchema>;
+export type ActiveConversationRunStatus = Extract<
+  ConversationRunProjection["status"],
+  "pending" | "running" | "waiting_for_tool"
+>;
+export type TerminalConversationRunStatus = Extract<
+  ConversationRunProjection["status"],
+  "completed" | "failed" | "cancelled"
+>;
 
 export const CreateConversationRunAcceptedSchema = z
   .object({
@@ -112,6 +157,59 @@ export const CompleteConversationRunResponseSchema = z
   })
   .passthrough();
 
+const AppendConversationRunEventsCamelRunSchema = z
+  .object({
+    runId: z.string().min(1),
+    conversationId: z.string().uuid(),
+    latestEventId: z.number().int().nonnegative(),
+    latestExternalEventSequence: z.number().int().nonnegative(),
+  })
+  .passthrough();
+
+const AppendConversationRunEventsSnakeRunSchema = z
+  .object({
+    run_id: z.string().min(1),
+    conversation_id: z.string().uuid(),
+    latest_event_id: z.number().int().nonnegative(),
+    latest_external_event_sequence: z.number().int().nonnegative(),
+  })
+  .passthrough();
+
+export const AppendConversationRunEventsResponseSchema = z.union([
+  z.object({
+    latestEventId: z.number().int().nonnegative(),
+    latestExternalEventSequence: z.number().int().nonnegative(),
+    appendedCount: z.number().int().nonnegative(),
+    run: AppendConversationRunEventsCamelRunSchema,
+  }),
+  z.object({
+    latest_event_id: z.number().int().nonnegative(),
+    latest_external_event_sequence: z.number().int().nonnegative(),
+    appended_count: z.number().int().nonnegative(),
+    run: AppendConversationRunEventsSnakeRunSchema,
+  }).transform((data) => ({
+    latestEventId: data.latest_event_id,
+    latestExternalEventSequence: data.latest_external_event_sequence,
+    appendedCount: data.appended_count,
+    run: {
+      ...data.run,
+      runId: data.run.run_id,
+      conversationId: data.run.conversation_id,
+      latestEventId: data.run.latest_event_id,
+      latestExternalEventSequence: data.run.latest_external_event_sequence,
+    },
+  })),
+]);
+
+export type AppendConversationRunEventsResponse = z.infer<
+  typeof AppendConversationRunEventsResponseSchema
+>;
+
+const ConversationRunErrorSchema = z.object({
+  detail: z.string().min(1).optional(),
+  error: z.string().min(1).optional(),
+});
+
 export interface ConversationAgentRunUsage {
   inputTokens: number;
   outputTokens: number;
@@ -141,6 +239,113 @@ export interface FinalizeConversationAgentRunInput {
   terminalErrorMessage?: string | null;
 }
 
+export class ConversationRunTerminalStateError extends Error {
+  readonly status: TerminalConversationRunStatus;
+  readonly run: ConversationRunProjection;
+
+  constructor(run: ConversationRunProjection, status: TerminalConversationRunStatus) {
+    super(`Conversation run ${run.runId} became ${status} before host execution finished`);
+    this.name = "ConversationRunTerminalStateError";
+    this.status = status;
+    this.run = run;
+  }
+}
+
+export class AppendConversationRunEventsError extends Error {
+  readonly status: number;
+  readonly detail: string | null;
+
+  constructor(input: {
+    status: number;
+    detail?: string | null;
+    statusText?: string;
+  }) {
+    const detail = input.detail?.trim() || input.statusText || `HTTP ${input.status}`;
+    super(`Append conversation run events failed (${input.status}): ${detail}`);
+    this.name = "AppendConversationRunEventsError";
+    this.status = input.status;
+    this.detail = input.detail?.trim() || null;
+  }
+}
+
+export function parseAppendConversationRunEventsErrorBody(bodyText: string): string | null {
+  if (!bodyText) {
+    return null;
+  }
+
+  try {
+    const parsed = ConversationRunErrorSchema.safeParse(JSON.parse(bodyText));
+    if (parsed.success) {
+      return parsed.data.detail ?? parsed.data.error ?? null;
+    }
+  } catch {
+    return bodyText;
+  }
+
+  return bodyText;
+}
+
+export function isIgnorableConversationRunAppendError(
+  error: unknown,
+): error is AppendConversationRunEventsError {
+  if (!(error instanceof AppendConversationRunEventsError)) {
+    return false;
+  }
+
+  if (error.status === 404) {
+    return true;
+  }
+
+  if (error.status !== 400) {
+    return false;
+  }
+
+  return (
+    error.detail === "Cannot append external events to a terminal run" ||
+    error.detail === "Cannot append external events while the run is waiting for a tool result"
+  );
+}
+
+export function isCursorMismatchConversationRunAppendError(
+  error: unknown,
+): error is AppendConversationRunEventsError {
+  return (
+    error instanceof AppendConversationRunEventsError &&
+    error.status === 400 &&
+    error.detail === "External run event cursor mismatch"
+  );
+}
+
+export function isActiveConversationRunStatus(
+  status: ConversationRunProjection["status"],
+): status is ActiveConversationRunStatus {
+  return status === "pending" || status === "running" || status === "waiting_for_tool";
+}
+
+async function waitForConversationRunPoll(
+  ms: number,
+  abortSignal?: AbortSignal,
+): Promise<void> {
+  if (ms <= 0 || abortSignal?.aborted) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    const timeoutId = dntShim.setTimeout(() => {
+      abortSignal?.removeEventListener("abort", resolveOnAbort);
+      resolve();
+    }, ms);
+
+    const resolveOnAbort = () => {
+      clearTimeout(timeoutId);
+      abortSignal?.removeEventListener("abort", resolveOnAbort);
+      resolve();
+    };
+
+    abortSignal?.addEventListener("abort", resolveOnAbort, { once: true });
+  });
+}
+
 async function controlPlaneJson<T>(input: {
   authToken: string;
   url: string;
@@ -148,11 +353,13 @@ async function controlPlaneJson<T>(input: {
   body?: unknown;
   responseSchema: z.ZodSchema<T>;
   operation: string;
+  abortSignal?: AbortSignal;
 }): Promise<T> {
-  const controller = new AbortController();
-  const timeout = dntShim.setTimeout(() => {
-    controller.abort();
-  }, AGENT_RUN_API_TIMEOUT_MS);
+  if (input.abortSignal?.aborted) {
+    throw new DOMException("This operation was aborted", "AbortError");
+  }
+
+  const timedAbort = createTimedAbortSignal(AGENT_RUN_API_TIMEOUT_MS, input.abortSignal);
 
   let response: Response;
   try {
@@ -163,15 +370,19 @@ async function controlPlaneJson<T>(input: {
         "Content-Type": "application/json",
       },
       ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
-      signal: controller.signal,
+      signal: timedAbort.signal,
     });
   } catch (error) {
-    if (error instanceof DOMException && error.name === "AbortError") {
+    if (
+      error instanceof DOMException &&
+      error.name === "AbortError" &&
+      !timedAbort.wasAbortedByCaller()
+    ) {
       throw new Error(`${input.operation} timed out after ${AGENT_RUN_API_TIMEOUT_MS}ms`);
     }
     throw error;
   } finally {
-    clearTimeout(timeout);
+    timedAbort.cleanup();
   }
 
   if (!response.ok) {
@@ -184,6 +395,141 @@ async function controlPlaneJson<T>(input: {
   return input.responseSchema.parse(await response.json());
 }
 
+export async function getConversationRun(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId: string;
+  abortSignal?: AbortSignal;
+}): Promise<ConversationRunProjection> {
+  return controlPlaneJson({
+    authToken: input.authToken,
+    url: `${input.apiUrl}/conversations/${input.conversationId}/runs/${input.runId}`,
+    responseSchema: ConversationRunProjectionSchema,
+    operation: "Read conversation durable run projection",
+    abortSignal: input.abortSignal,
+  });
+}
+
+export async function monitorConversationRunStatus(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId: string;
+  abortSignal?: AbortSignal;
+  pollIntervalMs: number;
+  onTerminal: (error: ConversationRunTerminalStateError) => void | Promise<void>;
+  onPollError?: (error: unknown) => void | Promise<void>;
+}): Promise<void> {
+  while (!input.abortSignal?.aborted) {
+    await waitForConversationRunPoll(input.pollIntervalMs, input.abortSignal);
+    if (input.abortSignal?.aborted) {
+      return;
+    }
+
+    try {
+      const run = await getConversationRun({
+        authToken: input.authToken,
+        apiUrl: input.apiUrl,
+        conversationId: input.conversationId,
+        runId: input.runId,
+        abortSignal: input.abortSignal,
+      });
+
+      if (isActiveConversationRunStatus(run.status)) {
+        continue;
+      }
+
+      if (
+        run.status === "completed" ||
+        run.status === "failed" ||
+        run.status === "cancelled"
+      ) {
+        await input.onTerminal(new ConversationRunTerminalStateError(run, run.status));
+      }
+      return;
+    } catch (error) {
+      if (input.abortSignal?.aborted) {
+        return;
+      }
+
+      if (error instanceof DOMException && error.name === "AbortError") {
+        return;
+      }
+
+      await input.onPollError?.(error);
+    }
+  }
+}
+
+export async function appendConversationRunEvents(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId: string;
+  expectedPreviousEventId?: number;
+  expectedPreviousExternalEventSequence?: number;
+  events: unknown[];
+  abortSignal?: AbortSignal;
+}): Promise<AppendConversationRunEventsResponse> {
+  if (input.abortSignal?.aborted) {
+    throw new DOMException("This operation was aborted", "AbortError");
+  }
+
+  const timedAbort = createTimedAbortSignal(AGENT_RUN_API_TIMEOUT_MS, input.abortSignal);
+
+  let response: Response;
+  try {
+    response = await fetch(
+      `${input.apiUrl}/conversations/${input.conversationId}/runs/${input.runId}/events`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${input.authToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          ...(input.expectedPreviousEventId !== undefined
+            ? { expected_previous_event_id: input.expectedPreviousEventId }
+            : {}),
+          ...(input.expectedPreviousExternalEventSequence !== undefined
+            ? {
+              expected_previous_external_event_sequence:
+                input.expectedPreviousExternalEventSequence,
+            }
+            : {}),
+          events: input.events,
+        }),
+        signal: timedAbort.signal,
+      },
+    );
+  } catch (error) {
+    if (
+      error instanceof DOMException &&
+      error.name === "AbortError" &&
+      !timedAbort.wasAbortedByCaller()
+    ) {
+      throw new Error(
+        `Append conversation run events timed out after ${AGENT_RUN_API_TIMEOUT_MS}ms`,
+      );
+    }
+    throw error;
+  } finally {
+    timedAbort.cleanup();
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new AppendConversationRunEventsError({
+      status: response.status,
+      detail: parseAppendConversationRunEventsErrorBody(body),
+      statusText: response.statusText,
+    });
+  }
+
+  return AppendConversationRunEventsResponseSchema.parse(await response.json());
+}
+
 export async function createConversationAgentRun(
   input: CreateConversationAgentRunInput,
 ): Promise<ConversationRunProjection> {
@@ -222,11 +568,11 @@ export async function createConversationAgentRun(
     operation: "Create canonical durable run",
   });
 
-  return controlPlaneJson({
+  return getConversationRun({
     authToken: input.authToken,
-    url: `${input.apiUrl}/conversations/${input.conversationId}/runs/${runId}`,
-    responseSchema: ConversationRunProjectionSchema,
-    operation: "Read conversation durable run projection",
+    apiUrl: input.apiUrl,
+    conversationId: input.conversationId,
+    runId,
   });
 }
 

package/src/src/agent/index.ts

@@ -193,16 +193,44 @@ export {
   fetchConversationRecord,
 } from "./conversation-bootstrap.js";
 export {
+  type ActiveConversationRunStatus,
+  appendConversationRunEvents,
+  AppendConversationRunEventsError,
+  type AppendConversationRunEventsResponse,
+  AppendConversationRunEventsResponseSchema,
   CompleteConversationRunResponseSchema,
   type ConversationAgentRunUsage,
   type ConversationRunProjection,
   ConversationRunProjectionSchema,
+  ConversationRunStatusSchema,
   type ConversationRunTargets,
   ConversationRunTargetsSchema,
+  ConversationRunTerminalStateError,
   createConversationAgentRun,
   finalizeConversationAgentRun,
+  getConversationRun,
+  isActiveConversationRunStatus,
+  isCursorMismatchConversationRunAppendError,
+  isIgnorableConversationRunAppendError,
+  monitorConversationRunStatus,
+  parseAppendConversationRunEventsErrorBody,
   resolveConversationRunTargets,
+  type TerminalConversationRunStatus,
 } from "./durable.js";
+export {
+  buildInvokeAgentChildRunLifecycleCustomEvent,
+  buildInvokeAgentChildRunProgressEvents,
+  buildInvokeAgentChildRunStateDelta,
+  type InvokeAgentChildRunLifecycleCustomEvent,
+  InvokeAgentChildRunLifecycleCustomEventSchema,
+  type InvokeAgentChildRunLifecycleValue,
+  InvokeAgentChildRunLifecycleValueSchema,
+  type InvokeAgentChildRunProgressEvent,
+  type InvokeAgentChildRunProgressInput,
+  type InvokeAgentChildRunStateDelta,
+  InvokeAgentChildRunStateDeltaSchema,
+  publishInvokeAgentChildRunProgress,
+} from "./invoke-agent-child-runs.js";
 export {
   type HostedChildLifecycleAdapter,
   type HostedChildLifecycleRunnerOptions,

package/src/src/agent/invoke-agent-child-runs.ts

@@ -0,0 +1,170 @@
+import "../../_dnt.polyfills.js";
+import { z } from "zod";
+import { appendConversationRunEvents, isIgnorableConversationRunAppendError } from "./durable.js";
+
+const AG_UI_CUSTOM_EVENT_TYPE = "CUSTOM";
+
+export const InvokeAgentChildRunLifecycleValueSchema = z.object({
+  toolCallId: z.string().min(1),
+  childConversationId: z.string().uuid(),
+  childRunId: z.string().min(1),
+  childMessageId: z.string().uuid(),
+  childAgentId: z.string().min(1),
+  description: z.string().min(1).optional(),
+  status: z.enum(["pending", "running", "waiting_for_tool", "completed", "failed", "cancelled"]),
+  sourceTargetKind: z.enum(["project", "production", "environment", "preview_branch"]).nullable()
+    .optional(),
+  runtimeTargetKind: z.enum(["production", "environment", "preview_branch"]).nullable().optional(),
+  targetEnvironmentId: z.string().uuid().nullable().optional(),
+  targetBranchId: z.string().uuid().nullable().optional(),
+});
+
+export type InvokeAgentChildRunLifecycleValue = z.infer<
+  typeof InvokeAgentChildRunLifecycleValueSchema
+>;
+
+export const InvokeAgentChildRunStateDeltaSchema = z.object({
+  type: z.literal("STATE_DELTA"),
+  delta: z.array(
+    z.object({
+      op: z.enum(["add", "replace"]),
+      path: z.string().min(1),
+      value: InvokeAgentChildRunLifecycleValueSchema,
+    }),
+  ),
+});
+
+export type InvokeAgentChildRunStateDelta = z.infer<typeof InvokeAgentChildRunStateDeltaSchema>;
+
+export const InvokeAgentChildRunLifecycleCustomEventSchema = z.object({
+  type: z.literal(AG_UI_CUSTOM_EVENT_TYPE),
+  name: z.literal("veryfront.invoke_agent.lifecycle"),
+  value: InvokeAgentChildRunLifecycleValueSchema,
+});
+
+export type InvokeAgentChildRunLifecycleCustomEvent = z.infer<
+  typeof InvokeAgentChildRunLifecycleCustomEventSchema
+>;
+
+export type InvokeAgentChildRunProgressInput = {
+  toolCallId: string;
+  childConversationId: string;
+  childRunId: string;
+  childMessageId: string;
+  childAgentId: string;
+  description?: string;
+  status: "pending" | "running" | "waiting_for_tool" | "completed" | "failed" | "cancelled";
+  sourceTargetKind?: "project" | "production" | "environment" | "preview_branch" | null;
+  runtimeTargetKind?: "production" | "environment" | "preview_branch" | null;
+  targetEnvironmentId?: string | null;
+  targetBranchId?: string | null;
+};
+
+export type InvokeAgentChildRunProgressEvent =
+  | InvokeAgentChildRunStateDelta
+  | InvokeAgentChildRunLifecycleCustomEvent;
+
+function buildInvokeAgentChildRunLifecycleValue(
+  input: InvokeAgentChildRunProgressInput,
+): InvokeAgentChildRunLifecycleValue {
+  return InvokeAgentChildRunLifecycleValueSchema.parse({
+    toolCallId: input.toolCallId,
+    childConversationId: input.childConversationId,
+    childRunId: input.childRunId,
+    childMessageId: input.childMessageId,
+    childAgentId: input.childAgentId,
+    ...(input.description ? { description: input.description } : {}),
+    status: input.status,
+    ...(input.sourceTargetKind !== undefined ? { sourceTargetKind: input.sourceTargetKind } : {}),
+    ...(input.runtimeTargetKind !== undefined
+      ? { runtimeTargetKind: input.runtimeTargetKind }
+      : {}),
+    ...(input.targetEnvironmentId !== undefined
+      ? { targetEnvironmentId: input.targetEnvironmentId }
+      : {}),
+    ...(input.targetBranchId !== undefined ? { targetBranchId: input.targetBranchId } : {}),
+  });
+}
+
+export function buildInvokeAgentChildRunStateDelta(
+  input: InvokeAgentChildRunProgressInput,
+): InvokeAgentChildRunStateDelta {
+  const escapedToolCallId = input.toolCallId.replaceAll("~", "~0").replaceAll("/", "~1");
+  return InvokeAgentChildRunStateDeltaSchema.parse({
+    type: "STATE_DELTA",
+    delta: [
+      {
+        op: input.status === "pending" ? "add" : "replace",
+        path: `/invokeAgentChildRuns/${escapedToolCallId}`,
+        value: buildInvokeAgentChildRunLifecycleValue(input),
+      },
+    ],
+  });
+}
+
+export function buildInvokeAgentChildRunLifecycleCustomEvent(
+  input: InvokeAgentChildRunProgressInput,
+): InvokeAgentChildRunLifecycleCustomEvent {
+  return InvokeAgentChildRunLifecycleCustomEventSchema.parse({
+    type: AG_UI_CUSTOM_EVENT_TYPE,
+    name: "veryfront.invoke_agent.lifecycle",
+    value: buildInvokeAgentChildRunLifecycleValue(input),
+  });
+}
+
+export function buildInvokeAgentChildRunProgressEvents(
+  input: InvokeAgentChildRunProgressInput,
+): readonly [InvokeAgentChildRunStateDelta, InvokeAgentChildRunLifecycleCustomEvent] {
+  return [
+    buildInvokeAgentChildRunStateDelta(input),
+    buildInvokeAgentChildRunLifecycleCustomEvent(input),
+  ] as const;
+}
+
+export async function publishInvokeAgentChildRunProgress(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId: string;
+  expectedPreviousEventId?: number;
+  expectedPreviousExternalEventSequence?: number;
+  toolCallId: string;
+  childAgentId: string;
+  childConversationId: string;
+  childRunId: string;
+  childMessageId: string;
+  description?: string;
+  status: "pending" | "running" | "waiting_for_tool" | "completed" | "failed" | "cancelled";
+  sourceTargetKind?: "project" | "production" | "environment" | "preview_branch" | null;
+  runtimeTargetKind?: "production" | "environment" | "preview_branch" | null;
+  targetEnvironmentId?: string | null;
+  targetBranchId?: string | null;
+  publishParentRunEvents?: (events: InvokeAgentChildRunProgressEvent[]) => Promise<void> | void;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const events = [...buildInvokeAgentChildRunProgressEvents(input)];
+
+  if (input.publishParentRunEvents) {
+    await input.publishParentRunEvents(events);
+    return;
+  }
+
+  try {
+    await appendConversationRunEvents({
+      authToken: input.authToken,
+      apiUrl: input.apiUrl,
+      conversationId: input.conversationId,
+      runId: input.runId,
+      expectedPreviousEventId: input.expectedPreviousEventId,
+      expectedPreviousExternalEventSequence: input.expectedPreviousExternalEventSequence,
+      events,
+      abortSignal: input.abortSignal,
+    });
+  } catch (error) {
+    if (isIgnorableConversationRunAppendError(error)) {
+      return;
+    }
+
+    throw error;
+  }
+}

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.233";
+export const VERSION = "0.1.235";