veryfront 0.1.419 → 0.1.421

package/src/src/agent/hosted-chat-execution-runtime.ts

@@ -0,0 +1,501 @@
+import {
+  buildChatStreamChunkMessageMetadata,
+  extractChatMessageMetadata,
+} from "../chat/chat-ui-message-helpers.js";
+import { getLastStreamStep } from "../chat/final-step-fallback.js";
+import type { ChatUiMessage, ChatUiMessageChunk, MessageMetadata } from "../chat/types.js";
+import {
+  buildDetachedFallbackChunks,
+  buildDetachedFallbackMessageState,
+  buildFinalizedMessageFallbackChunks,
+  buildFinalizedMessageState,
+} from "./hosted-finalized-message.js";
+import type {
+  HostedChatRuntimeStreamResult,
+  HostedChatRuntimeToUiMessageStreamOptions,
+} from "./hosted-chat-runtime-contract.js";
+import type { HostedLifecycleTerminalState } from "./hosted-lifecycle.js";
+import {
+  type ConversationHostedTerminalRuntimeAdapter,
+  type ConversationHostedTerminalStateInput,
+  dispatchConversationHostedStreamErrorState,
+  dispatchConversationHostedTerminalState,
+  resolveConversationHostedTerminalState,
+  toConversationHostedTerminalState,
+} from "./conversation-hosted-terminal.js";
+import {
+  createHostedMirroredUiStream,
+  type MirroredToolChunkState,
+} from "./mirrored-tool-chunk-state.js";
+import {
+  finalizeHostedDetached,
+  finalizeHostedResponse,
+  type FinalizeHostedResponseOptions,
+  type HostedDetachedFinalizationState,
+  type HostedResponseFinalizationState,
+} from "./hosted-stream-finalization.js";
+import {
+  getEmptyHostedFinalizedMessageTerminalError,
+  getHostedStreamErrorText,
+  shouldFailEmptyHostedFinalizedMessage,
+} from "./hosted-stream-terminal-error.js";
+import type { ConversationRunChunkMirror } from "./conversation-run-chunk-mirror.js";
+import type { BuildChatStreamChunkMessageMetadataInput } from "../chat/chat-ui-message-helpers.js";
+import type { createChatStreamWatchdog } from "../chat/stream-watchdog.js";
+
+const INCOMPLETE_TOOL_CALLS_PART_ERROR_TEXT = "Assistant ended before tool execution completed";
+
+const FINALIZATION_TERMINAL_STATE_FALLBACK_MODEL_ID = "";
+
+export interface HostedChatExecutionRuntime {
+  agentUIStream: AsyncIterable<ChatUiMessageChunk<MessageMetadata>>;
+  fail: (error: unknown) => Promise<void>;
+  waitForFinish: () => Promise<void>;
+}
+
+export interface HostedChatExecutionRuntimeLogger {
+  error: (message: string, metadata?: Record<string, unknown>) => void;
+  warn: (message: string, metadata?: Record<string, unknown>) => void;
+}
+
+export interface HostedChatExecutionRunContext {
+  withContext: <T>(fn: () => T) => T;
+  setMessageId?: (messageId: string) => void;
+}
+
+export interface HostedChatExecutionLifecycleAdapter
+  extends ConversationHostedTerminalRuntimeAdapter {
+  durableRootRun: {
+    runId: string;
+    messageId?: string | null;
+  } | null;
+  durableRunMirror: ConversationRunChunkMirror | null;
+}
+
+export type HostedChatExecutionRootStreamWatchdog = ReturnType<typeof createChatStreamWatchdog>;
+
+export interface HostedChatExecutionRuntimeBootstrap {
+  cleanup: () => Promise<void>;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  rootStreamWatchdog: HostedChatExecutionRootStreamWatchdog;
+  streamResult: HostedChatRuntimeStreamResult;
+  streamingMessageId: string | null;
+  capturedMessageId: string | null;
+  capturedConversationId?: string;
+  mirroredToolChunkState: MirroredToolChunkState;
+}
+
+export interface CreateHostedChatExecutionRuntimeInput {
+  agentId: string;
+  modelId: string;
+  originalMessages: ChatUiMessage[];
+  responseMessageId?: string;
+  runContext: HostedChatExecutionRunContext;
+  abortSignal: AbortSignal;
+  bootstrap: HostedChatExecutionRuntimeBootstrap;
+  logger?: HostedChatExecutionRuntimeLogger;
+  incompleteToolCallsPartErrorText?: string;
+}
+
+type SharedFinalizationHooks = Pick<
+  FinalizeHostedResponseOptions<ChatUiMessage, ChatUiMessageChunk<MessageMetadata>>,
+  | "resolveEmptyTerminalError"
+  | "appendFallbackChunk"
+  | "flushMirror"
+  | "dispatchTerminalState"
+  | "resolveTerminalState"
+  | "cleanup"
+  | "streamError"
+>;
+
+export function toHostedChatExecutionFinalState(
+  input: ConversationHostedTerminalStateInput,
+): HostedLifecycleTerminalState {
+  return toConversationHostedTerminalState({
+    state: input,
+    fallbackModelId: FINALIZATION_TERMINAL_STATE_FALLBACK_MODEL_ID,
+  });
+}
+
+export async function cleanupAfterHostedChatExecutionFinalization(input: {
+  cleanup: () => Promise<void>;
+  logger?: HostedChatExecutionRuntimeLogger;
+}): Promise<void> {
+  await input.cleanup().catch((cleanupError: unknown) => {
+    input.logger?.error("Runtime cleanup failed during finalization", {
+      error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+    });
+  });
+}
+
+export function createHostedChatStreamFinalizationHooks(input: {
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  cleanup: () => Promise<void>;
+  streamError: unknown;
+  logger?: HostedChatExecutionRuntimeLogger;
+}): SharedFinalizationHooks {
+  return {
+    resolveEmptyTerminalError: (
+      { finalStep, streamError }: { finalStep: unknown; streamError?: unknown | null },
+    ) => getEmptyHostedFinalizedMessageTerminalError({ finalStep, streamError }),
+    appendFallbackChunk: (chunk: ChatUiMessageChunk<MessageMetadata>) =>
+      input.lifecycleAdapter.durableRunMirror?.handleChunk(chunk),
+    flushMirror: () => input.lifecycleAdapter.durableRunMirror?.flush(),
+    dispatchTerminalState: async (terminalState) => {
+      await dispatchConversationHostedTerminalState(input.lifecycleAdapter, terminalState);
+    },
+    resolveTerminalState: ({ isAborted, hasIncompleteToolParts }: {
+      isAborted: boolean;
+      hasIncompleteToolParts: boolean;
+    }) =>
+      toHostedChatExecutionFinalState(
+        resolveConversationHostedTerminalState({ isAborted, hasIncompleteToolParts }),
+      ),
+    cleanup: () =>
+      cleanupAfterHostedChatExecutionFinalization({
+        cleanup: input.cleanup,
+        logger: input.logger,
+      }),
+    streamError: input.streamError,
+  };
+}
+
+export function createHostedChatFinalizeResponseBuildState(input: {
+  responseMessage: ChatUiMessage;
+  isAborted: boolean;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  mirroredToolChunkState: MirroredToolChunkState;
+  capturedMessageId: string | null;
+  incompleteToolCallsPartErrorText: string;
+}): (
+  finalStep: unknown,
+) => Promise<HostedResponseFinalizationState<ChatUiMessage, ChatUiMessageChunk<MessageMetadata>>> {
+  return async (finalStep) => {
+    const { persistedMessage, sanitizedFinalizedMessage, hasIncompleteFinalizedToolParts } =
+      buildFinalizedMessageState({
+        responseMessage: input.responseMessage,
+        isAborted: input.isAborted,
+        finalStep,
+        incompleteToolCallsPartErrorText: input.incompleteToolCallsPartErrorText,
+      });
+
+    return {
+      persistedMessage,
+      finalizedMessage: sanitizedFinalizedMessage,
+      fallbackChunks:
+        sanitizedFinalizedMessage.parts.length > 0 && input.lifecycleAdapter.durableRunMirror
+          ? buildFinalizedMessageFallbackChunks({
+            persistedMessage,
+            sanitizedFinalizedMessage,
+            finalStep,
+            mirroredToolChunkState: input.mirroredToolChunkState,
+            capturedMessageId: input.capturedMessageId,
+            hasIncompleteFinalizedToolParts,
+          })
+          : [],
+      hasIncompleteToolParts: hasIncompleteFinalizedToolParts,
+      metadata: extractChatMessageMetadata(sanitizedFinalizedMessage.metadata),
+    };
+  };
+}
+
+export function createHostedChatFinalizeDetachedBuildState(input: {
+  capturedMessageId: string | null;
+  isAborted: boolean;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  mirroredToolChunkState: MirroredToolChunkState;
+  mirroredDurableOutput: boolean;
+  incompleteToolCallsPartErrorText: string;
+}): (
+  finalStep: unknown,
+) => Promise<HostedDetachedFinalizationState<ChatUiMessageChunk<MessageMetadata>>> {
+  return async (finalStep) => {
+    const { finalizedFallbackMessage, hasIncompleteFallbackToolParts } =
+      buildDetachedFallbackMessageState({
+        capturedMessageId: input.capturedMessageId,
+        finalStep,
+        isAborted: input.isAborted,
+        incompleteToolCallsPartErrorText: input.incompleteToolCallsPartErrorText,
+      });
+    const fallbackParts = finalizedFallbackMessage.parts;
+
+    return {
+      hasContent: fallbackParts.length > 0,
+      fallbackChunks: fallbackParts.length > 0 && input.lifecycleAdapter.durableRunMirror &&
+          input.capturedMessageId
+        ? buildDetachedFallbackChunks({
+          fallbackParts,
+          finalStep,
+          mirroredToolChunkState: input.mirroredToolChunkState,
+          mirroredDurableOutput: input.mirroredDurableOutput,
+          capturedMessageId: input.capturedMessageId,
+          hasIncompleteFallbackToolParts,
+        })
+        : [],
+      hasIncompleteToolParts: hasIncompleteFallbackToolParts,
+    };
+  };
+}
+
+async function finalizeExecutionFailure(input: {
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  error: unknown;
+  conversationId?: string;
+  runId?: string;
+  logMessage: string;
+  logger?: HostedChatExecutionRuntimeLogger;
+}): Promise<void> {
+  await dispatchConversationHostedStreamErrorState(input.lifecycleAdapter, input.error).catch(
+    (finalizeError) => {
+      input.logger?.error(input.logMessage, {
+        conversationId: input.conversationId,
+        runId: input.runId,
+        error: finalizeError instanceof Error ? finalizeError.message : String(finalizeError),
+      });
+    },
+  );
+}
+
+function createStreamMessageMetadataBuilder(input: {
+  agentId: string;
+  modelId: string;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  streamingMessageId: string | null;
+}): HostedChatRuntimeToUiMessageStreamOptions["messageMetadata"] {
+  return ({ part }) =>
+    buildChatStreamChunkMessageMetadata(
+      {
+        agentId: input.agentId,
+        modelId: input.modelId,
+        ...(input.lifecycleAdapter.durableRootRun
+          ? { runId: input.lifecycleAdapter.durableRootRun.runId }
+          : {}),
+        ...(input.streamingMessageId ? { streamingMessageId: input.streamingMessageId } : {}),
+        part: {
+          type: part.type,
+          ...("totalUsage" in part ? { totalUsage: part.totalUsage } : {}),
+        },
+      } satisfies BuildChatStreamChunkMessageMetadataInput,
+    );
+}
+
+function logCleanupError(input: {
+  error: unknown;
+  logger?: HostedChatExecutionRuntimeLogger;
+}): void {
+  input.logger?.error("Runtime cleanup failed", {
+    error: input.error instanceof Error ? input.error.message : String(input.error),
+  });
+}
+
+async function finalizeResponseFinish(input: {
+  responseMessage: ChatUiMessage;
+  isAborted: boolean;
+  streamResult: { steps: PromiseLike<readonly unknown[]> };
+  lastStreamError: unknown;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  mirroredToolChunkState: MirroredToolChunkState;
+  capturedMessageId: string | null;
+  incompleteToolCallsPartErrorText: string;
+  cleanup: () => Promise<void>;
+  logger?: HostedChatExecutionRuntimeLogger;
+}): Promise<void> {
+  const hooks = createHostedChatStreamFinalizationHooks({
+    lifecycleAdapter: input.lifecycleAdapter,
+    cleanup: input.cleanup,
+    streamError: input.lastStreamError,
+    logger: input.logger,
+  });
+  const buildState = createHostedChatFinalizeResponseBuildState({
+    responseMessage: input.responseMessage,
+    isAborted: input.isAborted,
+    lifecycleAdapter: input.lifecycleAdapter,
+    mirroredToolChunkState: input.mirroredToolChunkState,
+    capturedMessageId: input.capturedMessageId,
+    incompleteToolCallsPartErrorText: input.incompleteToolCallsPartErrorText,
+  });
+
+  await finalizeHostedResponse({
+    isAborted: input.isAborted,
+    getFinalStep: () => getLastStreamStep(input.streamResult),
+    buildState,
+    shouldFailEmptyMessage: ({ isAborted, message }) =>
+      shouldFailEmptyHostedFinalizedMessage({ isAborted, message }),
+    ...hooks,
+  });
+}
+
+async function finalizeDetachedStreamEnd(input: {
+  capturedMessageId: string | null;
+  streamResult: { steps: PromiseLike<readonly unknown[]> };
+  isAborted: boolean;
+  lastStreamError: unknown;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  mirroredToolChunkState: MirroredToolChunkState;
+  mirroredDurableOutput: boolean;
+  incompleteToolCallsPartErrorText: string;
+  cleanup: () => Promise<void>;
+  logger?: HostedChatExecutionRuntimeLogger;
+}): Promise<void> {
+  const hooks = createHostedChatStreamFinalizationHooks({
+    lifecycleAdapter: input.lifecycleAdapter,
+    cleanup: input.cleanup,
+    streamError: input.lastStreamError,
+    logger: input.logger,
+  });
+  const buildState = createHostedChatFinalizeDetachedBuildState({
+    capturedMessageId: input.capturedMessageId,
+    isAborted: input.isAborted,
+    lifecycleAdapter: input.lifecycleAdapter,
+    mirroredToolChunkState: input.mirroredToolChunkState,
+    mirroredDurableOutput: input.mirroredDurableOutput,
+    incompleteToolCallsPartErrorText: input.incompleteToolCallsPartErrorText,
+  });
+
+  await finalizeHostedDetached({
+    isAborted: input.isAborted,
+    mirroredDurableOutput: input.mirroredDurableOutput,
+    getFinalStep: () => getLastStreamStep(input.streamResult),
+    buildState,
+    ...hooks,
+  });
+}
+
+function resolveStreamingMessageId(input: {
+  conversationId?: string;
+  lifecycleAdapter: HostedChatExecutionLifecycleAdapter;
+  runContext: HostedChatExecutionRunContext;
+}): string | null {
+  const streamingMessageId = input.lifecycleAdapter.durableRootRun?.messageId ?? null;
+  if (input.conversationId && !streamingMessageId) {
+    throw new Error("DURABLE_CHAT_ROOT_REQUIRES_CONVERSATION");
+  }
+
+  if (streamingMessageId) {
+    input.runContext.setMessageId?.(streamingMessageId);
+  }
+
+  return streamingMessageId;
+}
+
+export function createHostedChatExecutionRuntime(
+  input: CreateHostedChatExecutionRuntimeInput,
+): HostedChatExecutionRuntime {
+  let finishPromise: Promise<void> = Promise.resolve();
+  let lastStreamError: unknown = null;
+  let finishHandlerStarted = false;
+  let mirroredDurableOutput = false;
+  const incompleteToolCallsPartErrorText = input.incompleteToolCallsPartErrorText ??
+    INCOMPLETE_TOOL_CALLS_PART_ERROR_TEXT;
+  const streamingMessageId = resolveStreamingMessageId({
+    conversationId: input.bootstrap.capturedConversationId,
+    lifecycleAdapter: input.bootstrap.lifecycleAdapter,
+    runContext: input.runContext,
+  });
+
+  const finalizeDetachedStreamEndIfNeeded = async () => {
+    if (finishHandlerStarted) {
+      return;
+    }
+
+    finishHandlerStarted = true;
+    await finalizeDetachedStreamEnd({
+      capturedMessageId: input.bootstrap.capturedMessageId,
+      streamResult: input.bootstrap.streamResult,
+      isAborted: input.abortSignal.aborted,
+      lastStreamError,
+      lifecycleAdapter: input.bootstrap.lifecycleAdapter,
+      mirroredToolChunkState: input.bootstrap.mirroredToolChunkState,
+      mirroredDurableOutput,
+      incompleteToolCallsPartErrorText,
+      cleanup: input.bootstrap.cleanup,
+      logger: input.logger,
+    });
+  };
+
+  const fail = async (error: unknown) => {
+    await input.runContext.withContext(async () => {
+      input.bootstrap.rootStreamWatchdog.dispose();
+      await input.bootstrap.cleanup().catch((cleanupError: unknown) => {
+        logCleanupError({ error: cleanupError, logger: input.logger });
+      });
+      await finalizeExecutionFailure({
+        lifecycleAdapter: input.bootstrap.lifecycleAdapter,
+        error,
+        conversationId: input.bootstrap.capturedConversationId,
+        runId: input.bootstrap.lifecycleAdapter.durableRootRun?.runId,
+        logMessage: "Failed to mark durable chat root run as failed",
+        logger: input.logger,
+      });
+    });
+  };
+
+  const streamOptions: HostedChatRuntimeToUiMessageStreamOptions = {
+    sendReasoning: true,
+    originalMessages: input.originalMessages,
+    onError: (error) => {
+      lastStreamError = error;
+      return input.runContext.withContext(() => getHostedStreamErrorText(error));
+    },
+    onFinish: ({ responseMessage, isAborted }) => {
+      finishHandlerStarted = true;
+      finishPromise = input.runContext.withContext(() =>
+        finalizeResponseFinish({
+          responseMessage,
+          isAborted,
+          streamResult: input.bootstrap.streamResult,
+          lastStreamError,
+          lifecycleAdapter: input.bootstrap.lifecycleAdapter,
+          mirroredToolChunkState: input.bootstrap.mirroredToolChunkState,
+          capturedMessageId: input.bootstrap.capturedMessageId,
+          incompleteToolCallsPartErrorText,
+          cleanup: input.bootstrap.cleanup,
+          logger: input.logger,
+        }).catch((error) =>
+          finalizeExecutionFailure({
+            lifecycleAdapter: input.bootstrap.lifecycleAdapter,
+            error,
+            conversationId: input.bootstrap.capturedConversationId,
+            runId: input.bootstrap.lifecycleAdapter.durableRootRun?.runId,
+            logMessage: "Failed to finalize durable chat root run",
+            logger: input.logger,
+          })
+        )
+      );
+    },
+    messageMetadata: createStreamMessageMetadataBuilder({
+      agentId: input.agentId,
+      modelId: input.modelId,
+      lifecycleAdapter: input.bootstrap.lifecycleAdapter,
+      streamingMessageId,
+    }),
+  };
+
+  if (input.responseMessageId) {
+    const responseMessageId = input.responseMessageId;
+    streamOptions.generateMessageId = () => responseMessageId;
+  }
+  const agentUIStream = input.bootstrap.streamResult.toUIMessageStream(streamOptions);
+
+  return {
+    agentUIStream: createHostedMirroredUiStream({
+      sourceStream: agentUIStream,
+      rootStreamWatchdog: input.bootstrap.rootStreamWatchdog,
+      mirroredToolChunkState: input.bootstrap.mirroredToolChunkState,
+      appendChunk: (chunk) => input.bootstrap.lifecycleAdapter.durableRunMirror?.handleChunk(chunk),
+      setMirroredOutput: (value) => {
+        mirroredDurableOutput = value;
+      },
+      logger: input.logger,
+    }),
+    fail,
+    waitForFinish: async () => {
+      try {
+        await finalizeDetachedStreamEndIfNeeded();
+        await finishPromise;
+      } finally {
+        input.bootstrap.rootStreamWatchdog.dispose();
+      }
+    },
+  };
+}

package/src/src/agent/index.ts

@@ -799,6 +799,21 @@ export {
   type DetachedFallbackMessageState,
   type FinalizedMessageState,
 } from "./hosted-finalized-message.js";
+export {
+  cleanupAfterHostedChatExecutionFinalization,
+  createHostedChatExecutionRuntime,
+  type CreateHostedChatExecutionRuntimeInput,
+  createHostedChatFinalizeDetachedBuildState,
+  createHostedChatFinalizeResponseBuildState,
+  createHostedChatStreamFinalizationHooks,
+  type HostedChatExecutionLifecycleAdapter,
+  type HostedChatExecutionRootStreamWatchdog,
+  type HostedChatExecutionRunContext,
+  type HostedChatExecutionRuntime,
+  type HostedChatExecutionRuntimeBootstrap,
+  type HostedChatExecutionRuntimeLogger,
+  toHostedChatExecutionFinalState,
+} from "./hosted-chat-execution-runtime.js";
 export {
   finalizeHostedDetached,
   type FinalizeHostedDetachedOptions,

package/src/src/agent/runtime/index.ts

@@ -21,6 +21,7 @@ import {
   type MessagePart,
   type ResolvedRuntimeState,
   type ToolCall,
+  type ToolExecutionResultRequest,
   type ToolResultPart,
 } from "../types.js";
 import { ensureModelReady, type ModelRuntime, resolveModel } from "../../provider/index.js";
@@ -530,6 +531,15 @@ export class AgentRuntime {
     };
   }
 
+  private async notifyToolResult(
+    request: Omit<ToolExecutionResultRequest, "agentId">,
+  ): Promise<void> {
+    await this.config.onToolResult?.({
+      agentId: this.id,
+      ...request,
+    });
+  }
+
   /**
    * Generate a response (non-streaming)
    */
@@ -932,18 +942,27 @@ export class AgentRuntime {
               const startTime = Date.now();
 
               const cacheCtx = tryGetCacheKeyContext();
+              const executionContext = {
+                toolCallId: tc.toolCallId,
+                ...toolContext,
+                projectId: cacheCtx?.projectId ?? toolContext?.projectId,
+              };
               const result = await executeConfiguredTool(
                 tc.toolName,
                 toolCall.args,
                 this.config.tools,
-                {
-                  toolCallId: tc.toolCallId,
-                  ...toolContext,
-                  projectId: cacheCtx?.projectId ?? toolContext?.projectId,
-                },
+                executionContext,
                 allowedRemoteToolNames,
                 this.config.remoteTools,
               );
+              await this.notifyToolResult({
+                mode: "generate",
+                toolName: tc.toolName,
+                toolCallId: tc.toolCallId,
+                input: toolCall.args,
+                result,
+                context: executionContext,
+              });
 
               toolCall.status = "completed";
               toolCall.result = result;
@@ -1280,18 +1299,27 @@ export class AgentRuntime {
 
           callbacks?.onToolCall?.(toolCall);
 
+          const executionContext = {
+            toolCallId: tc.id,
+            ...toolContext,
+          };
           const result = await executeConfiguredTool(
             tc.name,
             toolCall.args,
             this.config.tools,
-            {
-              toolCallId: tc.id,
-              ...toolContext,
-            },
+            executionContext,
             allowedRemoteToolNames,
             this.config.remoteTools,
           );
           throwIfAborted(abortSignal);
+          await this.notifyToolResult({
+            mode: "stream",
+            toolName: tc.name,
+            toolCallId: tc.id,
+            input: toolCall.args,
+            result,
+            context: executionContext,
+          });
 
           toolCall.status = "completed";
           toolCall.result = result;

package/src/src/agent/types.ts

@@ -3,7 +3,7 @@
  **************************/
 
 import type { ModelRuntime } from "../provider/types.js";
-import type { RemoteToolSource, Tool } from "../tool/index.js";
+import type { RemoteToolSource, Tool, ToolExecutionContext } from "../tool/index.js";
 import { INVALID_ARGUMENT } from "../errors/error-registry.js";
 import type { Memory } from "./memory/memory-interface.js";
 
@@ -105,6 +105,12 @@ export interface AgentConfig {
    * host-owned context during a long-lived run.
    */
   resolveRuntimeState?: RuntimeStateResolver;
+  /**
+   * Optional hook invoked after the runtime executes a configured local,
+   * registry, integration, or remote tool and before the tool result is
+   * persisted or streamed back to callers.
+   */
+  onToolResult?: ToolExecutionResultHandler;
   /**
    * Enable skills for this agent.
    * - true: include all discovered skills from skills/ directory
@@ -158,6 +164,20 @@ export type RuntimeStateResolver = (
   request: RuntimeStateRequest,
 ) => ResolvedRuntimeState | undefined | Promise<ResolvedRuntimeState | undefined>;
 
+export interface ToolExecutionResultRequest {
+  agentId: string;
+  mode: "generate" | "stream";
+  toolName: string;
+  toolCallId: string;
+  input: Record<string, unknown>;
+  result: unknown;
+  context?: ToolExecutionContext;
+}
+
+export type ToolExecutionResultHandler = (
+  request: ToolExecutionResultRequest,
+) => void | Promise<void>;
+
 // Import for use in AgentMiddleware
 import type { AgentContext, AgentResponse } from "./schemas/index.js";
 

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