Add hosted child fork run context helper

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.405",
+  "version": "0.1.406",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [

src/agent/hosted-child-fork-run-context.test.ts

@@ -0,0 +1,78 @@
+import { assertEquals } from "@std/assert";
+import type { ChatMessageMetadata, ChatUiMessageChunk } from "#veryfront/chat/protocol.ts";
+import { createHostedChildForkRunContext } from "./hosted-child-fork-run-context.ts";
+
+Deno.test("createHostedChildForkRunContext wires stream mirror state and buffers", async () => {
+  const chunks: ChatUiMessageChunk<ChatMessageMetadata>[] = [];
+  const context = createHostedChildForkRunContext({
+    mirror: {
+      handleChunk: (chunk) => {
+        chunks.push(chunk);
+      },
+    },
+    messageId: "message-1",
+    pendingToolLogContext: {
+      conversationId: "conversation-1",
+      parentRunId: "run-1",
+      description: "Check the app",
+    },
+  });
+
+  assertEquals(context.streamMirrorContext.durableRunMirror, true);
+  assertEquals(context.streamMirrorContext.durableMessageId, "message-1");
+  assertEquals(context.streamMirrorContext.durableReasoningMessageId, "message-1:reasoning");
+  assertEquals(context.streamMirrorContext.hasStartedStep(), false);
+  assertEquals(context.streamMirrorContext.hasEmittedProgress(), false);
+  assertEquals(context.streamState.finalText, "");
+  assertEquals(context.toolCalls, []);
+  assertEquals(context.toolResults, []);
+
+  context.streamMirrorContext.markDurableStepStarted();
+  await context.streamMirrorContext.appendDurableMirrorChunk({ type: "start-step" });
+
+  assertEquals(context.streamMirrorContext.hasStartedStep(), true);
+  assertEquals(context.streamMirrorContext.hasEmittedProgress(), true);
+  assertEquals(chunks, [{ type: "start-step" }]);
+});
+
+Deno.test("createHostedChildForkRunContext closes pending tool calls with host logger", async () => {
+  const chunks: ChatUiMessageChunk<ChatMessageMetadata>[] = [];
+  const warnings: Array<{ message: string; context: Record<string, unknown> }> = [];
+  const context = createHostedChildForkRunContext({
+    mirror: {
+      handleChunk: (chunk) => {
+        chunks.push(chunk);
+      },
+    },
+    pendingToolLogContext: {
+      conversationId: "conversation-1",
+      parentRunId: "run-1",
+      description: "Check the app",
+    },
+    pendingToolLogWriter: {
+      warn: (message, logContext) => {
+        warnings.push({ message, context: logContext });
+      },
+    },
+  });
+
+  context.pendingToolLifecycle.upsertPendingToolCall("tool-call-1", {
+    phase: "awaiting_result",
+    toolName: "read_file",
+    input: { path: "README.md" },
+  });
+
+  await context.pendingToolLifecycle.closePendingToolCalls({ kind: "aborted" });
+
+  assertEquals(chunks.map((chunk) => chunk.type), ["tool-input-start", "tool-output-error"]);
+  assertEquals(warnings.length, 1);
+  assertEquals(warnings[0]?.message, "Closing incomplete child fork tool lifecycles");
+  assertEquals(warnings[0]?.context, {
+    conversationId: "conversation-1",
+    runId: "run-1",
+    description: "Check the app",
+    reason: "aborted",
+    toolCallIds: ["tool-call-1"],
+    errorMessage: null,
+  });
+});

src/agent/hosted-child-fork-run-context.ts

@@ -0,0 +1,99 @@
+import type { ChatMessageMetadata, ChatUiMessageChunk } from "#veryfront/chat/protocol.ts";
+import {
+  createHostedChildMirrorContext,
+  type HostedChildChunkMirror,
+  type HostedChildMirrorContext,
+} from "./hosted-child-mirror.ts";
+import {
+  createHostedChildPendingToolLifecycle,
+  createHostedChildPendingToolLifecycleLogger,
+  type HostedChildPendingToolLifecycleLogContext,
+  type HostedChildPendingToolLifecycleLogWriter,
+} from "./hosted-child-pending-tool-lifecycle.ts";
+import type { HostedChildForkPendingToolLifecycle } from "./hosted-child-fork-stream-execution.ts";
+
+export interface HostedChildForkToolCallSnapshot {
+  toolName: string;
+  toolCallId: string;
+  input?: unknown;
+}
+
+export interface HostedChildForkToolResultSnapshot {
+  toolName: string;
+  toolCallId: string;
+  input: unknown;
+  output: unknown;
+}
+
+export interface HostedChildForkStreamState {
+  finalText: string;
+}
+
+export interface HostedChildForkStreamMirrorContext {
+  durableRunMirror: boolean;
+  durableMessageId: string | null;
+  durableReasoningMessageId: string | null;
+  durableMirrorState: HostedChildMirrorContext["state"];
+  appendDurableMirrorChunk: (chunk: ChatUiMessageChunk<ChatMessageMetadata>) => Promise<void>;
+  closeDurableMirrorReasoning: () => Promise<void>;
+  closeDurableMirrorText: () => Promise<void>;
+  markDurableStepStarted: () => void;
+  hasStartedStep: () => boolean;
+  hasEmittedProgress: () => boolean;
+}
+
+export interface HostedChildForkRunContext {
+  mirrorContext: HostedChildMirrorContext;
+  streamMirrorContext: HostedChildForkStreamMirrorContext;
+  pendingToolLifecycle: HostedChildForkPendingToolLifecycle;
+  toolCalls: HostedChildForkToolCallSnapshot[];
+  toolResults: HostedChildForkToolResultSnapshot[];
+  streamState: HostedChildForkStreamState;
+}
+
+export interface HostedChildForkRunContextInput {
+  mirror: HostedChildChunkMirror | null;
+  messageId?: string | null;
+  reasoningMessageId?: string | null;
+  pendingToolLogContext: HostedChildPendingToolLifecycleLogContext;
+  pendingToolLogWriter?: HostedChildPendingToolLifecycleLogWriter;
+}
+
+export function createHostedChildForkRunContext(
+  input: HostedChildForkRunContextInput,
+): HostedChildForkRunContext {
+  const mirrorContext = createHostedChildMirrorContext({
+    mirror: input.mirror,
+    messageId: input.messageId,
+    reasoningMessageId: input.reasoningMessageId,
+  });
+  const streamMirrorContext: HostedChildForkStreamMirrorContext = {
+    durableRunMirror: Boolean(mirrorContext.mirror),
+    durableMessageId: mirrorContext.messageId,
+    durableReasoningMessageId: mirrorContext.reasoningMessageId,
+    durableMirrorState: mirrorContext.state,
+    appendDurableMirrorChunk: mirrorContext.appendChunk,
+    closeDurableMirrorReasoning: mirrorContext.closeReasoningSegment,
+    closeDurableMirrorText: mirrorContext.closeTextSegment,
+    markDurableStepStarted: mirrorContext.markStepStarted,
+    hasStartedStep: mirrorContext.hasStartedStep,
+    hasEmittedProgress: mirrorContext.hasEmittedProgress,
+  };
+
+  return {
+    mirrorContext,
+    streamMirrorContext,
+    pendingToolLifecycle: createHostedChildPendingToolLifecycle({
+      appendMirrorChunk: streamMirrorContext.appendDurableMirrorChunk,
+      logger: input.pendingToolLogWriter
+        ? createHostedChildPendingToolLifecycleLogger(
+          input.pendingToolLogContext,
+          input.pendingToolLogWriter,
+        )
+        : undefined,
+    }),
+    toolCalls: [],
+    toolResults: [],
+    streamState: { finalText: "" },
+  };
+}

src/agent/index.ts

@@ -422,6 +422,15 @@ export {
   HOSTED_CHILD_FORK_INSTRUCTIONS_BASE,
   type HostedChildForkInstructionsContext,
 } from "./hosted-child-fork-instructions.ts";
+export {
+  createHostedChildForkRunContext,
+  type HostedChildForkRunContext,
+  type HostedChildForkRunContextInput,
+  type HostedChildForkStreamMirrorContext,
+  type HostedChildForkStreamState,
+  type HostedChildForkToolCallSnapshot,
+  type HostedChildForkToolResultSnapshot,
+} from "./hosted-child-fork-run-context.ts";
 export {
   executeHostedChildForkStream,
   type ExecuteHostedChildForkStreamInput,

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