veryfront 0.1.233 → 0.1.234

package/esm/deno.d.ts

@@ -19,6 +19,7 @@ declare namespace _default {
         "./agent": string;
         "./agent/conversation-bootstrap": string;
         "./agent/durable": string;
+        "./agent/invoke-agent-child-runs": string;
         "./channels/control-plane": string;
         "./channels/invoke": string;
         "./tool": string;

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.233",
+    "version": "0.1.234",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "workspace": [
@@ -32,6 +32,7 @@ export default {
         "./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/esm/src/agent/durable.d.ts

@@ -16,6 +16,14 @@ export declare function resolveConversationRunTargets(input: {
     projectId?: string | null;
     branchId?: string | null;
 }): ConversationRunTargets;
+export declare const ConversationRunStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    pending: "pending";
+    completed: "completed";
+    running: "running";
+    cancelled: "cancelled";
+    waiting_for_tool: "waiting_for_tool";
+}>;
 export declare const ConversationRunProjectionSchema: z.ZodPipe<z.ZodObject<{
     runId: z.ZodOptional<z.ZodString>;
     run_id: z.ZodOptional<z.ZodString>;
@@ -87,6 +95,53 @@ export declare const CompleteConversationRunResponseSchema: z.ZodObject<{
         }>;
     }, z.core.$loose>;
 }, z.core.$loose>;
+export declare const AppendConversationRunEventsResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
+    latestEventId: z.ZodNumber;
+    latestExternalEventSequence: z.ZodNumber;
+    appendedCount: z.ZodNumber;
+    run: z.ZodObject<{
+        runId: z.ZodString;
+        conversationId: z.ZodString;
+        latestEventId: z.ZodNumber;
+        latestExternalEventSequence: z.ZodNumber;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodPipe<z.ZodObject<{
+    latest_event_id: z.ZodNumber;
+    latest_external_event_sequence: z.ZodNumber;
+    appended_count: z.ZodNumber;
+    run: z.ZodObject<{
+        run_id: z.ZodString;
+        conversation_id: z.ZodString;
+        latest_event_id: z.ZodNumber;
+        latest_external_event_sequence: z.ZodNumber;
+    }, z.core.$loose>;
+}, z.core.$strip>, z.ZodTransform<{
+    latestEventId: number;
+    latestExternalEventSequence: number;
+    appendedCount: number;
+    run: {
+        runId: string;
+        conversationId: string;
+        latestEventId: number;
+        latestExternalEventSequence: number;
+        run_id: string;
+        conversation_id: string;
+        latest_event_id: number;
+        latest_external_event_sequence: number;
+    };
+}, {
+    latest_event_id: number;
+    latest_external_event_sequence: number;
+    appended_count: number;
+    run: {
+        [x: string]: unknown;
+        run_id: string;
+        conversation_id: string;
+        latest_event_id: number;
+        latest_external_event_sequence: number;
+    };
+}>>]>;
+export type AppendConversationRunEventsResponse = z.infer<typeof AppendConversationRunEventsResponseSchema>;
 export interface ConversationAgentRunUsage {
     inputTokens: number;
     outputTokens: number;
@@ -113,6 +168,35 @@ export interface FinalizeConversationAgentRunInput {
     terminalErrorCode?: string | null;
     terminalErrorMessage?: string | null;
 }
+export declare class AppendConversationRunEventsError extends Error {
+    readonly status: number;
+    readonly detail: string | null;
+    constructor(input: {
+        status: number;
+        detail?: string | null;
+        statusText?: string;
+    });
+}
+export declare function parseAppendConversationRunEventsErrorBody(bodyText: string): string | null;
+export declare function isIgnorableConversationRunAppendError(error: unknown): error is AppendConversationRunEventsError;
+export declare function isCursorMismatchConversationRunAppendError(error: unknown): error is AppendConversationRunEventsError;
+export declare function getConversationRun(input: {
+    authToken: string;
+    apiUrl: string;
+    conversationId: string;
+    runId: string;
+    abortSignal?: AbortSignal;
+}): Promise<ConversationRunProjection>;
+export declare function appendConversationRunEvents(input: {
+    authToken: string;
+    apiUrl: string;
+    conversationId: string;
+    runId: string;
+    expectedPreviousEventId?: number;
+    expectedPreviousExternalEventSequence?: number;
+    events: unknown[];
+    abortSignal?: AbortSignal;
+}): Promise<AppendConversationRunEventsResponse>;
 export declare function createConversationAgentRun(input: CreateConversationAgentRunInput): Promise<ConversationRunProjection>;
 export declare function finalizeConversationAgentRun(input: FinalizeConversationAgentRunInput): Promise<void>;
 //# sourceMappingURL=durable.d.ts.map

package/esm/src/agent/durable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../../../src/src/agent/durable.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AAEjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,4BAA4B;;;;;;;;;;iBAIvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,sBAAsB,CAoBzB;AAED,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCxC,CAAC;AAEL,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;GAiB5C,CAAC;AAEL,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;iBAWlC,CAAC;AAEjB,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AA6CD,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,yBAAyB,CAAC,CA0CpC;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../../../src/src/agent/durable.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AAEjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB,eAAO,MAAM,4BAA4B;;;;;;;;;;iBAIvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,sBAAsB,CAoBzB;AAED,eAAO,MAAM,2BAA2B;;;;;;;EAOtC,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCxC,CAAC;AAEL,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;GAiB5C,CAAC;AAEL,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;iBAWlC,CAAC;AAoBjB,eAAO,MAAM,yCAAyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAwBpD,CAAC;AAEH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,yCAAyC,CACjD,CAAC;AAOF,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEnB,KAAK,EAAE;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;CAOF;AAED,wBAAgB,yCAAyC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAezF;AAED,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,gCAAgC,CAiB3C;AAED,wBAAgB,0CAA0C,CACxD,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,gCAAgC,CAM3C;AAmDD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAQrC;AAED,wBAAsB,2BAA2B,CAAC,KAAK,EAAE;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qCAAqC,CAAC,EAAE,MAAM,CAAC;IAC/C,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B,GAAG,OAAO,CAAC,mCAAmC,CAAC,CAyD/C;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,yBAAyB,CAAC,CA0CpC;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/esm/src/agent/durable.js

@@ -2,6 +2,31 @@ import "../../_dnt.polyfills.js";
 import * as dntShim from "../../_dnt.shims.js";
 import { z } from "zod";
 const AGENT_RUN_API_TIMEOUT_MS = 15_000;
+function createTimedAbortSignal(timeoutMs, 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(),
@@ -26,6 +51,14 @@ export function resolveConversationRunTargets(input) {
                 targetBranchId: null,
             });
 }
+export const ConversationRunStatusSchema = z.enum([
+    "pending",
+    "running",
+    "waiting_for_tool",
+    "completed",
+    "failed",
+    "cancelled",
+]);
 export const ConversationRunProjectionSchema = z
     .object({
     runId: z.string().min(1).optional(),
@@ -38,7 +71,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) => {
@@ -92,11 +125,100 @@ export const CompleteConversationRunResponseSchema = z
         .passthrough(),
 })
     .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,
+        },
+    })),
+]);
+const ConversationRunErrorSchema = z.object({
+    detail: z.string().min(1).optional(),
+    error: z.string().min(1).optional(),
+});
+export class AppendConversationRunEventsError extends Error {
+    status;
+    detail;
+    constructor(input) {
+        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) {
+    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) {
+    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) {
+    return (error instanceof AppendConversationRunEventsError &&
+        error.status === 400 &&
+        error.detail === "External run event cursor mismatch");
+}
 async function controlPlaneJson(input) {
-    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;
     try {
         response = await fetch(input.url, {
@@ -106,17 +228,19 @@ async function controlPlaneJson(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) {
         const body = await response.text().catch(() => "");
@@ -124,6 +248,63 @@ async function controlPlaneJson(input) {
     }
     return input.responseSchema.parse(await response.json());
 }
+export async function getConversationRun(input) {
+    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 appendConversationRunEvents(input) {
+    if (input.abortSignal?.aborted) {
+        throw new DOMException("This operation was aborted", "AbortError");
+    }
+    const timedAbort = createTimedAbortSignal(AGENT_RUN_API_TIMEOUT_MS, input.abortSignal);
+    let 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) {
     const targets = resolveConversationRunTargets({
         projectId: input.projectId ?? null,
@@ -158,11 +339,11 @@ export async function createConversationAgentRun(input) {
         responseSchema: CreateConversationRunAcceptedSchema,
         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,
     });
 }
 export async function finalizeConversationAgentRun(input) {

package/esm/src/agent/index.d.ts

@@ -90,7 +90,8 @@ export { normalizeAgUiRuntimeMessages } from "./ag-ui-runtime-support.js";
 export { type AgUiBrowserEncodedEvent, type AgUiBrowserEncoderState, type AgUiBrowserRunFinishedMetadata, type AgUiRuntimeStreamEvent, buildAgUiBrowserFinalizeResponse, createAgUiBrowserEncoderState, finalizeAgUiBrowserEvents, mapRuntimeStreamEventToAgUiBrowserEvents, } from "./ag-ui-browser-encoder.js";
 export { type AgUiBrowserResponseEncoder, type AgUiBrowserResponseExecution, type AgUiBrowserResponseRequestState, 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 { appendConversationRunEvents, AppendConversationRunEventsError, type AppendConversationRunEventsResponse, AppendConversationRunEventsResponseSchema, CompleteConversationRunResponseSchema, type ConversationAgentRunUsage, type ConversationRunProjection, ConversationRunProjectionSchema, ConversationRunStatusSchema, type ConversationRunTargets, ConversationRunTargetsSchema, createConversationAgentRun, finalizeConversationAgentRun, getConversationRun, isCursorMismatchConversationRunAppendError, isIgnorableConversationRunAppendError, parseAppendConversationRunEventsErrorBody, resolveConversationRunTargets, } 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, type HostedChildLifecycleRunResult, type HostedChildLifecycleTerminalState, runHostedChildLifecycle, } from "./hosted-child-lifecycle.js";
 export { type HostedLifecycleAdapter, type HostedLifecycleExecution, type HostedLifecycleRunnerOptions, type HostedLifecycleRunResult, type HostedLifecycleTerminalState, runHostedLifecycle, } from "./hosted-lifecycle.js";
 export { mergeToolCallInput, mergeToolInputDelta, parseDataStreamSseEvents, parseToolInputObject, streamDataStreamEvents, stripLeadingEmptyObjectPlaceholder, } from "./data-stream.js";

package/esm/src/agent/index.d.ts.map

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

package/esm/src/agent/index.js

@@ -89,7 +89,8 @@ export { normalizeAgUiRuntimeMessages } from "./ag-ui-runtime-support.js";
 export { buildAgUiBrowserFinalizeResponse, createAgUiBrowserEncoderState, finalizeAgUiBrowserEvents, mapRuntimeStreamEventToAgUiBrowserEvents, } from "./ag-ui-browser-encoder.js";
 export { createAgUiBrowserResponseStream, } from "./ag-ui-browser-response-stream.js";
 export { bootstrapConversationAgentRun, ConversationMessageRecordSchema, ConversationRecordSchema, createConversationMessage, createConversationRecord, ensureConversationProjectLink, fetchConversationRecord, } from "./conversation-bootstrap.js";
-export { CompleteConversationRunResponseSchema, ConversationRunProjectionSchema, ConversationRunTargetsSchema, createConversationAgentRun, finalizeConversationAgentRun, resolveConversationRunTargets, } from "./durable.js";
+export { appendConversationRunEvents, AppendConversationRunEventsError, AppendConversationRunEventsResponseSchema, CompleteConversationRunResponseSchema, ConversationRunProjectionSchema, ConversationRunStatusSchema, ConversationRunTargetsSchema, createConversationAgentRun, finalizeConversationAgentRun, getConversationRun, isCursorMismatchConversationRunAppendError, isIgnorableConversationRunAppendError, parseAppendConversationRunEventsErrorBody, resolveConversationRunTargets, } from "./durable.js";
+export { buildInvokeAgentChildRunLifecycleCustomEvent, buildInvokeAgentChildRunProgressEvents, buildInvokeAgentChildRunStateDelta, InvokeAgentChildRunLifecycleCustomEventSchema, InvokeAgentChildRunLifecycleValueSchema, InvokeAgentChildRunStateDeltaSchema, publishInvokeAgentChildRunProgress, } from "./invoke-agent-child-runs.js";
 export { runHostedChildLifecycle, } from "./hosted-child-lifecycle.js";
 export { runHostedLifecycle, } from "./hosted-lifecycle.js";
 export { mergeToolCallInput, mergeToolInputDelta, parseDataStreamSseEvents, parseToolInputObject, streamDataStreamEvents, stripLeadingEmptyObjectPlaceholder, } from "./data-stream.js";

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.233",
+  "version": "0.1.234",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",
@@ -77,6 +77,10 @@
       "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.233",
+  "version": "0.1.234",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [
@@ -32,6 +32,7 @@ export default {
     "./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/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) => {
@@ -112,6 +149,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 +231,71 @@ export interface FinalizeConversationAgentRunInput {
   terminalErrorMessage?: string | null;
 }
 
+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"
+  );
+}
+
 async function controlPlaneJson<T>(input: {
   authToken: string;
   url: string;
@@ -148,11 +303,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 +320,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 +345,90 @@ 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 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 +467,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,39 @@ export {
   fetchConversationRecord,
 } from "./conversation-bootstrap.js";
 export {
+  appendConversationRunEvents,
+  AppendConversationRunEventsError,
+  type AppendConversationRunEventsResponse,
+  AppendConversationRunEventsResponseSchema,
   CompleteConversationRunResponseSchema,
   type ConversationAgentRunUsage,
   type ConversationRunProjection,
   ConversationRunProjectionSchema,
+  ConversationRunStatusSchema,
   type ConversationRunTargets,
   ConversationRunTargetsSchema,
   createConversationAgentRun,
   finalizeConversationAgentRun,
+  getConversationRun,
+  isCursorMismatchConversationRunAppendError,
+  isIgnorableConversationRunAppendError,
+  parseAppendConversationRunEventsErrorBody,
   resolveConversationRunTargets,
 } 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.234";