veryfront 0.1.232 → 0.1.234

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

@@ -0,0 +1,145 @@
+import "../../_dnt.polyfills.js";
+import { z } from "zod";
+export declare const InvokeAgentChildRunLifecycleValueSchema: z.ZodObject<{
+    toolCallId: z.ZodString;
+    childConversationId: z.ZodString;
+    childRunId: z.ZodString;
+    childMessageId: z.ZodString;
+    childAgentId: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        completed: "completed";
+        running: "running";
+        cancelled: "cancelled";
+        waiting_for_tool: "waiting_for_tool";
+    }>;
+    sourceTargetKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        project: "project";
+        production: "production";
+        environment: "environment";
+        preview_branch: "preview_branch";
+    }>>>;
+    runtimeTargetKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        production: "production";
+        environment: "environment";
+        preview_branch: "preview_branch";
+    }>>>;
+    targetEnvironmentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    targetBranchId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type InvokeAgentChildRunLifecycleValue = z.infer<typeof InvokeAgentChildRunLifecycleValueSchema>;
+export declare const InvokeAgentChildRunStateDeltaSchema: z.ZodObject<{
+    type: z.ZodLiteral<"STATE_DELTA">;
+    delta: z.ZodArray<z.ZodObject<{
+        op: z.ZodEnum<{
+            replace: "replace";
+            add: "add";
+        }>;
+        path: z.ZodString;
+        value: z.ZodObject<{
+            toolCallId: z.ZodString;
+            childConversationId: z.ZodString;
+            childRunId: z.ZodString;
+            childMessageId: z.ZodString;
+            childAgentId: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            status: z.ZodEnum<{
+                failed: "failed";
+                pending: "pending";
+                completed: "completed";
+                running: "running";
+                cancelled: "cancelled";
+                waiting_for_tool: "waiting_for_tool";
+            }>;
+            sourceTargetKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                project: "project";
+                production: "production";
+                environment: "environment";
+                preview_branch: "preview_branch";
+            }>>>;
+            runtimeTargetKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                production: "production";
+                environment: "environment";
+                preview_branch: "preview_branch";
+            }>>>;
+            targetEnvironmentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            targetBranchId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InvokeAgentChildRunStateDelta = z.infer<typeof InvokeAgentChildRunStateDeltaSchema>;
+export declare const InvokeAgentChildRunLifecycleCustomEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"CUSTOM">;
+    name: z.ZodLiteral<"veryfront.invoke_agent.lifecycle">;
+    value: z.ZodObject<{
+        toolCallId: z.ZodString;
+        childConversationId: z.ZodString;
+        childRunId: z.ZodString;
+        childMessageId: z.ZodString;
+        childAgentId: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            completed: "completed";
+            running: "running";
+            cancelled: "cancelled";
+            waiting_for_tool: "waiting_for_tool";
+        }>;
+        sourceTargetKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            project: "project";
+            production: "production";
+            environment: "environment";
+            preview_branch: "preview_branch";
+        }>>>;
+        runtimeTargetKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            production: "production";
+            environment: "environment";
+            preview_branch: "preview_branch";
+        }>>>;
+        targetEnvironmentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        targetBranchId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+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;
+export declare function buildInvokeAgentChildRunStateDelta(input: InvokeAgentChildRunProgressInput): InvokeAgentChildRunStateDelta;
+export declare function buildInvokeAgentChildRunLifecycleCustomEvent(input: InvokeAgentChildRunProgressInput): InvokeAgentChildRunLifecycleCustomEvent;
+export declare function buildInvokeAgentChildRunProgressEvents(input: InvokeAgentChildRunProgressInput): readonly [InvokeAgentChildRunStateDelta, InvokeAgentChildRunLifecycleCustomEvent];
+export declare 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>;
+//# sourceMappingURL=invoke-agent-child-runs.d.ts.map

package/esm/src/agent/invoke-agent-child-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-agent-child-runs.d.ts","sourceRoot":"","sources":["../../../src/src/agent/invoke-agent-child-runs.ts"],"names":[],"mappings":"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"}

package/esm/src/agent/invoke-agent-child-runs.js

@@ -0,0 +1,101 @@
+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 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 const InvokeAgentChildRunLifecycleCustomEventSchema = z.object({
+    type: z.literal(AG_UI_CUSTOM_EVENT_TYPE),
+    name: z.literal("veryfront.invoke_agent.lifecycle"),
+    value: InvokeAgentChildRunLifecycleValueSchema,
+});
+function buildInvokeAgentChildRunLifecycleValue(input) {
+    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) {
+    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) {
+    return InvokeAgentChildRunLifecycleCustomEventSchema.parse({
+        type: AG_UI_CUSTOM_EVENT_TYPE,
+        name: "veryfront.invoke_agent.lifecycle",
+        value: buildInvokeAgentChildRunLifecycleValue(input),
+    });
+}
+export function buildInvokeAgentChildRunProgressEvents(input) {
+    return [
+        buildInvokeAgentChildRunStateDelta(input),
+        buildInvokeAgentChildRunLifecycleCustomEvent(input),
+    ];
+}
+export async function publishInvokeAgentChildRunProgress(input) {
+    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/esm/src/utils/version-constant.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.232";
+export declare const VERSION = "0.1.234";
 //# sourceMappingURL=version-constant.d.ts.map

package/esm/src/utils/version-constant.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.232",
+  "version": "0.1.234",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",
@@ -69,10 +69,18 @@
       "import": "./esm/src/agent/index.js",
       "types": "./esm/src/agent/index.d.ts"
     },
+    "./agent/conversation-bootstrap": {
+      "import": "./esm/src/agent/conversation-bootstrap.js",
+      "types": "./esm/src/agent/conversation-bootstrap.d.ts"
+    },
     "./agent/durable": {
       "import": "./esm/src/agent/durable.js",
       "types": "./esm/src/agent/durable.d.ts"
     },
+    "./agent/invoke-agent-child-runs": {
+      "import": "./esm/src/agent/invoke-agent-child-runs.js",
+      "types": "./esm/src/agent/invoke-agent-child-runs.d.ts"
+    },
     "./channels/control-plane": {
       "import": "./esm/src/channels/control-plane.js",
       "types": "./esm/src/channels/control-plane.d.ts"

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.232",
+  "version": "0.1.234",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [
@@ -30,7 +30,9 @@ export default {
     "./markdown": "./src/markdown/index.ts",
     "./mdx": "./src/mdx/index.ts",
     "./agent": "./src/agent/index.ts",
+    "./agent/conversation-bootstrap": "./src/agent/conversation-bootstrap.ts",
     "./agent/durable": "./src/agent/durable.ts",
+    "./agent/invoke-agent-child-runs": "./src/agent/invoke-agent-child-runs.ts",
     "./channels/control-plane": "./src/channels/control-plane.ts",
     "./channels/invoke": "./src/channels/invoke.ts",
     "./tool": "./src/tool/index.ts",

package/src/src/agent/conversation-bootstrap.ts

@@ -0,0 +1,195 @@
+import "../../_dnt.polyfills.js";
+import * as dntShim from "../../_dnt.shims.js";
+import { z } from "zod";
+import { type ConversationRunProjection, createConversationAgentRun } from "./durable.js";
+
+const CONVERSATION_API_TIMEOUT_MS = 15_000;
+
+export const ConversationRecordSchema = z
+  .object({
+    id: z.string(),
+    projectId: z.string().nullable().optional(),
+    project_id: z.string().nullable().optional(),
+  })
+  .passthrough()
+  .transform((data) => ({
+    id: data.id,
+    projectId: data.projectId ?? data.project_id ?? null,
+  }));
+
+export const ConversationMessageRecordSchema = z.object({
+  id: z.string().uuid(),
+});
+
+export type ConversationRecord = z.infer<typeof ConversationRecordSchema>;
+export type ConversationMessageRecord = z.infer<typeof ConversationMessageRecordSchema>;
+
+async function controlPlaneJson<T>(input: {
+  authToken: string;
+  url: string;
+  method?: "GET" | "POST" | "PATCH";
+  body?: unknown;
+  responseSchema: z.ZodSchema<T>;
+  operation: string;
+}): Promise<T> {
+  const controller = new AbortController();
+  const timeout = dntShim.setTimeout(() => controller.abort(), CONVERSATION_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 ${CONVERSATION_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());
+}
+
+function buildConversationPath(apiUrl: string, conversationId: string): string {
+  return `${apiUrl}/conversations/${conversationId}`;
+}
+
+function buildConversationMessagesPath(apiUrl: string, conversationId: string): string {
+  return `${buildConversationPath(apiUrl, conversationId)}/messages`;
+}
+
+export async function fetchConversationRecord(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+}): Promise<ConversationRecord> {
+  return controlPlaneJson({
+    authToken: input.authToken,
+    url: buildConversationPath(input.apiUrl, input.conversationId),
+    responseSchema: ConversationRecordSchema,
+    operation: "Fetch conversation",
+  });
+}
+
+export async function ensureConversationProjectLink(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  projectId: string;
+}): Promise<void> {
+  const conversation = await fetchConversationRecord(input);
+
+  if (conversation.projectId === input.projectId) return;
+  if (conversation.projectId !== null) {
+    throw new Error(
+      `Conversation ${input.conversationId} is already linked to a different project (${conversation.projectId})`,
+    );
+  }
+
+  await controlPlaneJson({
+    authToken: input.authToken,
+    url: buildConversationPath(input.apiUrl, input.conversationId),
+    method: "PATCH",
+    body: { project_id: input.projectId },
+    responseSchema: ConversationRecordSchema,
+    operation: "Link conversation to project",
+  });
+}
+
+export async function createConversationRecord(input: {
+  authToken: string;
+  apiUrl: string;
+  body: unknown;
+}): Promise<ConversationRecord> {
+  return controlPlaneJson({
+    authToken: input.authToken,
+    url: `${input.apiUrl}/conversations`,
+    method: "POST",
+    body: input.body,
+    responseSchema: ConversationRecordSchema,
+    operation: "Create conversation",
+  });
+}
+
+export async function createConversationMessage(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  body: unknown;
+}): Promise<ConversationMessageRecord> {
+  return controlPlaneJson({
+    authToken: input.authToken,
+    url: buildConversationMessagesPath(input.apiUrl, input.conversationId),
+    method: "POST",
+    body: input.body,
+    responseSchema: ConversationMessageRecordSchema,
+    operation: "Create conversation message",
+  });
+}
+
+export interface BootstrapConversationAgentRunResult {
+  conversation: ConversationRecord;
+  message: ConversationMessageRecord;
+  run: ConversationRunProjection;
+}
+
+export async function bootstrapConversationAgentRun(input: {
+  authToken: string;
+  apiUrl: string;
+  parentConversationId?: string;
+  ensureProjectId?: string;
+  conversationBody: unknown;
+  handoffMessageBody: unknown;
+  runId?: string;
+  agentId: string;
+  projectId?: string | null;
+  branchId?: string | null;
+}): Promise<BootstrapConversationAgentRunResult> {
+  if (input.parentConversationId && input.ensureProjectId) {
+    await ensureConversationProjectLink({
+      authToken: input.authToken,
+      apiUrl: input.apiUrl,
+      conversationId: input.parentConversationId,
+      projectId: input.ensureProjectId,
+    });
+  }
+
+  const conversation = await createConversationRecord({
+    authToken: input.authToken,
+    apiUrl: input.apiUrl,
+    body: input.conversationBody,
+  });
+  const effectiveProjectId = input.projectId ?? conversation.projectId;
+  const message = await createConversationMessage({
+    authToken: input.authToken,
+    apiUrl: input.apiUrl,
+    conversationId: conversation.id,
+    body: input.handoffMessageBody,
+  });
+  const run = await createConversationAgentRun({
+    authToken: input.authToken,
+    apiUrl: input.apiUrl,
+    conversationId: conversation.id,
+    runId: input.runId,
+    agentId: input.agentId,
+    projectId: effectiveProjectId,
+    branchId: input.branchId,
+  });
+
+  return { conversation, message, run };
+}