@botbotgo/runtime 1.0.0

package/src/runtime/execution/agentRunExecutor.ts

@@ -0,0 +1,499 @@
+import { AgentStreamService, type DrainAgentStreamOptions, type DrainAgentStreamResult } from "../stream/agentStream.js";
+import { AgentMessageService } from "../stream/agentMessages.js";
+import { type AgentWorkspaceState } from "../../state/workspaceState.js";
+import { RunArtifactService } from "../stream/runArtifacts.js";
+import { type AgentRuntimeEventPublisher } from "../events/eventPublisher.js";
+import { AgentRunProgress } from "./agentRunProgress.js";
+import { AgentRunStateFactory, type ExecutionContext, type RetryState } from "./agentRunState.js";
+import { RunCompletionPolicy } from "./policies/runCompletionPolicy.js";
+import { RunErrorPolicy } from "./policies/runErrorPolicy.js";
+import { RunPromptBuilder } from "./policies/runPromptBuilder.js";
+import { RunSummaryFormatter } from "./policies/runSummaryFormatter.js";
+import { RuntimeDelay } from "./policies/runtimeDelay.js";
+import { type AgentRuntimeRunOptions, type ConstructorParams, type RunStreamFactory } from "./agentRunExecutor.types.js";
+export type { AgentRuntimeRunOptions } from "./agentRunExecutor.types.js";
+
+export class AgentRunExecutor {
+  private readonly rootDir: string;
+  private readonly workspace: AgentWorkspaceState;
+  private readonly eventsPublisher: AgentRuntimeEventPublisher;
+  private readonly runLogger: (message: string) => void;
+  private readonly defaultIncompleteRunMaxRetries?: number;
+  private readonly defaultEmptyRunMaxRetries?: number;
+  private readonly defaultMalformedToolCallMaxRetries?: number;
+  private readonly defaultIdleTimeoutMaxRetries?: number;
+  private readonly defaultHeartbeatIntervalMs?: number;
+  private readonly defaultIdleTimeoutMs?: number;
+  private readonly artifactValidator?: ConstructorParams["artifactValidator"];
+
+  public constructor(params: ConstructorParams) {
+    this.rootDir = params.rootDir;
+    this.workspace = params.workspace;
+    this.eventsPublisher = params.events;
+    this.runLogger = params.runLogger;
+    this.defaultIncompleteRunMaxRetries = params.defaultIncompleteRunMaxRetries;
+    this.defaultEmptyRunMaxRetries = params.defaultEmptyRunMaxRetries;
+    this.defaultMalformedToolCallMaxRetries = params.defaultMalformedToolCallMaxRetries;
+    this.defaultIdleTimeoutMaxRetries = params.defaultIdleTimeoutMaxRetries;
+    this.defaultHeartbeatIntervalMs = params.defaultHeartbeatIntervalMs;
+    this.defaultIdleTimeoutMs = params.defaultIdleTimeoutMs;
+    this.artifactValidator = params.artifactValidator;
+  }
+
+  public async runStream<TChunk>(
+    params: {
+      prompt: string;
+      createStream: RunStreamFactory<TChunk>;
+    } & AgentRuntimeRunOptions<TChunk>,
+  ): Promise<DrainAgentStreamResult<TChunk>> {
+    const context = await this.createRunContext(params);
+    const retryState = AgentRunStateFactory.createRetryState(
+      context.trackedArtifactFiles.length > 0,
+      params,
+      {
+        incompleteRunMaxRetries: this.defaultIncompleteRunMaxRetries,
+        emptyRunMaxRetries: this.defaultEmptyRunMaxRetries,
+        malformedToolCallMaxRetries: this.defaultMalformedToolCallMaxRetries,
+        idleTimeoutMaxRetries: this.defaultIdleTimeoutMaxRetries,
+      },
+    );
+
+    try {
+      const result = await this.executeLoop(context, params, retryState);
+      await this.finalizeSuccessfulRun(context, params, result);
+      return result;
+    } catch (error) {
+      await this.finalizeFailedRun(context, error);
+      throw error;
+    }
+  }
+
+  private async createRunContext<TChunk>(
+    params: {
+      prompt: string;
+      createStream: RunStreamFactory<TChunk>;
+    } & AgentRuntimeRunOptions<TChunk>,
+  ): Promise<ExecutionContext<TChunk>> {
+    const effectivePrompt = RunPromptBuilder.buildExecutionPrompt(params.prompt);
+    const trackedArtifactFiles = RunArtifactService.resolveTrackedArtifactFiles(
+      this.rootDir,
+      this.workspace.artifactFiles,
+      effectivePrompt,
+    );
+    const trackedPaths = RunArtifactService.buildTrackedPaths(
+      this.rootDir,
+      this.workspace.runStateFile,
+      this.workspace.todosFile,
+      trackedArtifactFiles,
+    );
+    const requiredArtifactPaths = this.toRelativeArtifactPaths(trackedArtifactFiles);
+    this.emitRunPrepare(effectivePrompt, trackedPaths, requiredArtifactPaths);
+
+    const run = await this.workspace.prepareRun({
+      prompt: effectivePrompt,
+      fallbackThreadId: params.fallbackThreadId,
+      resumeHint:
+        params.resumeHint ??
+        `A previous run was interrupted. Continue from the current workspace state, especially ${trackedPaths.join(", ")}, instead of restarting from scratch.`,
+    });
+    await RunArtifactService.resetTrackedArtifactsForFreshRun(run.previousState?.status, trackedArtifactFiles);
+    await run.start();
+    this.emitRunStart(effectivePrompt, run.threadId);
+
+    return {
+      run,
+      effectivePrompt,
+      trackedArtifactFiles,
+      trackedPaths,
+      requiredArtifactPaths,
+      runInput: run.input,
+      runConfig: run.config,
+      pendingToolCall: undefined,
+      lastLoggedSummary: "",
+      lastStepCount: 0,
+      lastSummary: "",
+    };
+  }
+
+  private emitRunPrepare(prompt: string, trackedPaths: string[], requiredArtifactPaths: string[]): void {
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.prepare",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.workspace",
+      payload: { prompt, trackedPaths, requiredArtifactPaths },
+    });
+  }
+
+  private emitRunStart(prompt: string, threadId: string): void {
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.start",
+      from: "user",
+      to: "agent-runtime2.runtime",
+      payload: { prompt, threadId },
+    });
+  }
+
+  private async executeLoop<TChunk>(
+    context: ExecutionContext<TChunk>,
+    params: {
+      createStream: RunStreamFactory<TChunk>;
+    } & AgentRuntimeRunOptions<TChunk>,
+    retryState: RetryState,
+  ): Promise<DrainAgentStreamResult<TChunk>> {
+    while (true) {
+      try {
+        const result = await this.drainStream(context, params);
+        if (await this.resolvePostDrainAction(context, result, params, retryState) === "complete") {
+          return result;
+        }
+      } catch (error) {
+        if (!(await this.handleExecutionError(context, error, retryState))) {
+          throw error;
+        }
+      }
+    }
+  }
+
+  private async drainStream<TChunk>(
+    context: ExecutionContext<TChunk>,
+    params: {
+      createStream: RunStreamFactory<TChunk>;
+    } & AgentRuntimeRunOptions<TChunk>,
+  ): Promise<DrainAgentStreamResult<TChunk>> {
+    return AgentStreamService.drain(await params.createStream({
+      input: context.runInput,
+      config: context.runConfig,
+    }), this.createDrainOptions(context, params));
+  }
+
+  private createDrainOptions<TChunk>(
+    context: ExecutionContext<TChunk>,
+    params: AgentRuntimeRunOptions<TChunk>,
+  ): DrainAgentStreamOptions<TChunk> {
+    const idleTimeoutMs = this.resolveIdleTimeoutMs(params.streamOptions?.idleTimeoutMs);
+    return {
+      ...params.streamOptions,
+      onChunk: async (chunk) => {
+        this.eventsPublisher.emit({
+          name: "agent.runtime2.stream.chunk",
+          from: "agent-runtime2.stream",
+          to: "agent-runtime2.runtime",
+          payload: { chunk },
+        });
+        await params.streamOptions?.onChunk?.(chunk);
+      },
+      heartbeatIntervalMs:
+        params.heartbeatIntervalMs ??
+        params.streamOptions?.heartbeatIntervalMs ??
+        this.defaultHeartbeatIntervalMs ??
+        10_000,
+      idleTimeoutMs,
+      summarizeChunk: params.summarizeChunk ?? AgentMessageService.summarizeAgentChunk,
+      onHeartbeat: async (event) => {
+        this.eventsPublisher.emit({
+          name: "agent.runtime2.stream.heartbeat",
+          from: "agent-runtime2.stream",
+          to: "agent-runtime2.runtime",
+          payload: event,
+        });
+        this.runLogger(`... waiting for model output  (${(event.elapsedMs / 1000).toFixed(1)}s)`);
+      },
+      shouldStopOnSummary: async (event) => {
+        if (await params.streamOptions?.shouldStopOnSummary?.(event)) {
+          return true;
+        }
+        return AgentRunProgress.shouldStopForSummary(
+          context,
+          event.summary,
+          event.chunk,
+          (trackedArtifactFiles) => this.areTrackedArtifactsReady(trackedArtifactFiles, context, params),
+        );
+      },
+      shouldStop: async (chunk) => {
+        if (await params.streamOptions?.shouldStop?.(chunk)) {
+          return true;
+        }
+        return AgentRunProgress.shouldStopForChunk(
+          context,
+          params,
+          chunk,
+          (trackedArtifactFiles) => this.areTrackedArtifactsReady(trackedArtifactFiles, context, params),
+        );
+      },
+      onSummary: async (event) => {
+        context.lastStepCount = event.stepIndex;
+        context.lastSummary = event.summary;
+        this.eventsPublisher.emit({
+          name: "agent.runtime2.stream.summary",
+          from: "agent-runtime2.stream",
+          to: "agent-runtime2.runtime",
+          payload: event,
+        });
+        if (params.onSummary) {
+          await params.onSummary(event);
+        } else {
+          AgentRunProgress.logRunSummary(context, event.summary, event.elapsedMs, this.runLogger);
+        }
+        await context.run.update(event.stepIndex, event.summary);
+      },
+    };
+  }
+
+  private resolveIdleTimeoutMs(requestedIdleTimeoutMs: number | undefined): number {
+    if (requestedIdleTimeoutMs != null) return requestedIdleTimeoutMs;
+    const configuredIdleTimeoutMs = Number(process.env.LLM_IDLE_TIMEOUT_MS);
+    return this.defaultIdleTimeoutMs ?? (Number.isFinite(configuredIdleTimeoutMs) && configuredIdleTimeoutMs > 0
+      ? configuredIdleTimeoutMs
+      : 300_000);
+  }
+
+  private async resolvePostDrainAction<TChunk>(
+    context: ExecutionContext<TChunk>,
+    result: DrainAgentStreamResult<TChunk>,
+    params: AgentRuntimeRunOptions<TChunk>,
+    retryState: RetryState,
+  ): Promise<"retry" | "complete"> {
+    if (await this.shouldRetryEmptyResult(context, result, params, retryState)) {
+      await RuntimeDelay.wait(Math.min(1000 * retryState.emptyRetryCount, 3000));
+      return "retry";
+    }
+    if (await this.shouldRetryIncompleteRun(context, result, params, retryState)) {
+      context.runInput = {
+        messages: [{
+          role: "user",
+          content: RunPromptBuilder.buildIncompleteRetryPrompt({
+            prompt: context.effectivePrompt,
+            trackedPaths: context.trackedPaths,
+            requiredArtifactPaths: context.requiredArtifactPaths,
+            lastSummary: result.lastSummary,
+          }),
+        }],
+      };
+      return "retry";
+    }
+    return "complete";
+  }
+
+  private shouldRetryEmptyResult<TChunk>(
+    context: ExecutionContext<TChunk>,
+    result: DrainAgentStreamResult<TChunk>,
+    params: AgentRuntimeRunOptions<TChunk>,
+    retryState: RetryState,
+  ): Promise<boolean> | boolean {
+    const noProgressPromise = this.areTrackedArtifactsReady(context.trackedArtifactFiles, context, params)
+      .then((artifactsReady) =>
+        !artifactsReady &&
+      result.stepCount === 0 &&
+      (!result.lastSummary || result.lastSummary.trim().length === 0));
+    return noProgressPromise.then((noProgress) => {
+      if (!noProgress || retryState.emptyRetryCount >= retryState.emptyRunMaxRetries) return false;
+
+      retryState.emptyRetryCount += 1;
+      this.eventsPublisher.emit({
+        name: "agent.runtime2.run.retry.empty",
+        from: "agent-runtime2.runtime",
+        to: "agent-runtime2.runtime",
+        payload: {
+          attempt: retryState.emptyRetryCount,
+          maxRetries: retryState.emptyRunMaxRetries,
+        },
+      });
+      this.runLogger(
+        `! Retrying after empty model response (attempt ${retryState.emptyRetryCount}/${retryState.emptyRunMaxRetries})`,
+      );
+      context.runConfig = {
+        configurable: { thread_id: `${context.run.threadId}-empty-${retryState.emptyRetryCount}-${Date.now()}` },
+      };
+      return true;
+    });
+  }
+
+  private async shouldRetryIncompleteRun<TChunk>(
+    context: ExecutionContext<TChunk>,
+    result: DrainAgentStreamResult<TChunk>,
+    params: AgentRuntimeRunOptions<TChunk>,
+    retryState: RetryState,
+  ): Promise<boolean> {
+    const artifactsReady = await this.areTrackedArtifactsReady(context.trackedArtifactFiles, context, params);
+    const appearsCompleted = context.trackedArtifactFiles.length > 0
+      ? artifactsReady
+      : RunCompletionPolicy.hasAssistantFinalMessage(result.lastChunk);
+    if ((artifactsReady && appearsCompleted) || retryState.incompleteRetryCount >= retryState.incompleteRunMaxRetries) {
+      return false;
+    }
+
+    retryState.incompleteRetryCount += 1;
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.retry.incomplete",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.runtime",
+      payload: {
+        attempt: retryState.incompleteRetryCount,
+        maxRetries: retryState.incompleteRunMaxRetries,
+        lastSummary: result.lastSummary,
+      },
+    });
+    this.runLogger(
+      `! Retrying to finish incomplete run (attempt ${retryState.incompleteRetryCount}/${retryState.incompleteRunMaxRetries})`,
+    );
+    context.pendingToolCall = undefined;
+    context.lastLoggedSummary = "";
+    return true;
+  }
+
+  private async handleExecutionError<TChunk>(
+    context: ExecutionContext<TChunk>,
+    error: unknown,
+    retryState: RetryState,
+  ): Promise<boolean> {
+    if (RunErrorPolicy.isIdleTimeoutError(error) &&
+      retryState.idleTimeoutRetryCount < retryState.idleTimeoutMaxRetries) {
+      retryState.idleTimeoutRetryCount += 1;
+      this.eventsPublisher.emit({
+        name: "agent.runtime2.run.retry.idle_timeout",
+        from: "agent-runtime2.runtime",
+        to: "agent-runtime2.runtime",
+        payload: {
+          attempt: retryState.idleTimeoutRetryCount,
+          maxRetries: retryState.idleTimeoutMaxRetries,
+        },
+      });
+      this.runLogger(
+        `! Retrying after idle timeout (attempt ${retryState.idleTimeoutRetryCount}/${retryState.idleTimeoutMaxRetries})`,
+      );
+      return true;
+    }
+    if (RunErrorPolicy.isTransientModelError(error)) {
+      return this.handleTransientModelError(context, error, retryState);
+    }
+    if (!RunErrorPolicy.isRecoverableToolCallError(error) ||
+      retryState.malformedRetryCount >= retryState.malformedToolCallMaxRetries) {
+      return false;
+    }
+
+    retryState.malformedRetryCount += 1;
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.retry.tool_call",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.runtime",
+      payload: {
+        attempt: retryState.malformedRetryCount,
+        maxRetries: retryState.malformedToolCallMaxRetries,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+    this.runLogger(
+      `! Retrying after recoverable tool-call error (attempt ${retryState.malformedRetryCount}/${retryState.malformedToolCallMaxRetries})`,
+    );
+    return true;
+  }
+
+  private async handleTransientModelError<TChunk>(
+    context: ExecutionContext<TChunk>,
+    error: unknown,
+    retryState: RetryState,
+  ): Promise<boolean> {
+    if (retryState.transientModelRetryCount >= retryState.transientModelMaxRetries) {
+      throw RunErrorPolicy.createTransientModelError(error);
+    }
+
+    retryState.transientModelRetryCount += 1;
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.retry.transient_model",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.runtime",
+      payload: {
+        attempt: retryState.transientModelRetryCount,
+        maxRetries: retryState.transientModelMaxRetries,
+      },
+    });
+    this.runLogger(
+      `! Retrying after transient model error (${retryState.transientModelRetryCount}/${retryState.transientModelMaxRetries})`,
+    );
+    await RuntimeDelay.wait(Math.min(1000 * retryState.transientModelRetryCount, 3000));
+    context.runConfig = {
+      configurable: { thread_id: `${context.run.threadId}-transient-${retryState.transientModelRetryCount}-${Date.now()}` },
+    };
+    return true;
+  }
+
+  private async finalizeSuccessfulRun<TChunk>(
+    context: ExecutionContext<TChunk>,
+    params: AgentRuntimeRunOptions<TChunk>,
+    result: DrainAgentStreamResult<TChunk>,
+  ): Promise<void> {
+    if (!params.onSummary && context.pendingToolCall) {
+      this.runLogger(RunSummaryFormatter.formatRunStep(
+        context.pendingToolCall.summary,
+        context.pendingToolCall.elapsedMs,
+      ));
+    }
+    await context.run.finish(result.stepCount, result.lastSummary);
+
+    const artifactsReady = await this.areTrackedArtifactsReady(context.trackedArtifactFiles, context, params);
+    const appearsCompleted = context.trackedArtifactFiles.length > 0
+      ? artifactsReady
+      : RunCompletionPolicy.hasAssistantFinalMessage(result.lastChunk);
+    if (!artifactsReady || !appearsCompleted) {
+      throw new Error(
+        `Run ended before completion (summary="${result.lastSummary || "n/a"}", stepCount=${result.stepCount}, artifactsReady=${artifactsReady})`,
+      );
+    }
+    if (!params.onSummary && context.lastLoggedSummary !== "Run completed") {
+      this.runLogger(RunSummaryFormatter.formatRunStep("Run completed", result.durationMs));
+    }
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.done",
+      from: "agent-runtime2.runtime",
+      to: "user",
+      payload: {
+        threadId: context.run.threadId,
+        stepCount: result.stepCount,
+        durationMs: result.durationMs,
+        lastSummary: result.lastSummary,
+      },
+    });
+  }
+
+  private async finalizeFailedRun<TChunk>(context: ExecutionContext<TChunk>, error: unknown): Promise<void> {
+    const summary = context.lastSummary || "Run failed";
+    await context.run.finish(context.lastStepCount, summary).catch(() => {});
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.run.error",
+      from: "agent-runtime2.runtime",
+      to: "user",
+      payload: {
+        threadId: context.run.threadId,
+        stepCount: context.lastStepCount,
+        lastSummary: summary,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+
+  private async areTrackedArtifactsReady<TChunk>(
+    trackedArtifactFiles: string[],
+    context: Pick<ExecutionContext<TChunk>, "requiredArtifactPaths">,
+    params: Pick<AgentRuntimeRunOptions<TChunk>, "artifactValidator">,
+  ): Promise<boolean> {
+    if (!RunArtifactService.areArtifactsUsable(trackedArtifactFiles)) {
+      return false;
+    }
+    const validator = params.artifactValidator ?? this.artifactValidator;
+    if (!validator) {
+      return true;
+    }
+    return await validator({
+      rootDir: this.rootDir,
+      trackedArtifactFiles,
+      requiredArtifactPaths: context.requiredArtifactPaths,
+    });
+  }
+
+  private toRelativeArtifactPaths(trackedArtifactFiles: string[]): string[] {
+    const normalizedRoot = this.rootDir.replace(/\\/g, "/");
+    return trackedArtifactFiles
+      .map((file) => file.replace(/\\/g, "/"))
+      .map((file) => file.startsWith(`${normalizedRoot}/`) ? file.slice(normalizedRoot.length + 1) : file);
+  }
+}

package/src/runtime/execution/agentRunExecutor.types.ts

@@ -0,0 +1,39 @@
+import type { DrainAgentStreamOptions } from "../stream/agentStream.js";
+import type { AgentWorkspaceState } from "../../state/workspaceState.js";
+
+export interface AgentRuntimeRunOptions<TChunk> {
+  resumeHint?: string;
+  fallbackThreadId?: string;
+  malformedToolCallMaxRetries?: number;
+  incompleteRunMaxRetries?: number;
+  emptyRunMaxRetries?: number;
+  idleTimeoutMaxRetries?: number;
+  streamOptions?: Omit<DrainAgentStreamOptions<TChunk>, "onSummary" | "summarizeChunk" | "onHeartbeat">;
+  onSummary?: DrainAgentStreamOptions<TChunk>["onSummary"];
+  summarizeChunk?: (chunk: TChunk) => string | null | undefined;
+  heartbeatIntervalMs?: number;
+  artifactValidator?: (context: {
+    rootDir: string;
+    trackedArtifactFiles: string[];
+    requiredArtifactPaths: string[];
+  }) => boolean | Promise<boolean>;
+}
+
+export interface ConstructorParams {
+  rootDir: string;
+  workspace: AgentWorkspaceState;
+  events: import("../events/eventPublisher.js").AgentRuntimeEventPublisher;
+  runLogger: (message: string) => void;
+  defaultIncompleteRunMaxRetries?: number;
+  defaultEmptyRunMaxRetries?: number;
+  defaultMalformedToolCallMaxRetries?: number;
+  defaultIdleTimeoutMaxRetries?: number;
+  defaultHeartbeatIntervalMs?: number;
+  defaultIdleTimeoutMs?: number;
+  artifactValidator?: AgentRuntimeRunOptions<unknown>["artifactValidator"];
+}
+
+export type RunStreamFactory<TChunk> = (context: {
+  input: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["input"];
+  config: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["config"];
+}) => Promise<AsyncIterable<TChunk>> | AsyncIterable<TChunk>;

package/src/runtime/execution/agentRunProgress.ts

@@ -0,0 +1,67 @@
+import { AgentMessageService } from "../stream/agentMessages.js";
+import { RunCompletionPolicy } from "./policies/runCompletionPolicy.js";
+import { RunSummaryFormatter } from "./policies/runSummaryFormatter.js";
+import type { AgentRuntimeRunOptions } from "./agentRunExecutor.js";
+import type { ExecutionContext } from "./agentRunState.js";
+
+export class AgentRunProgress {
+  public static shouldStopForSummary<TChunk>(
+    context: ExecutionContext<TChunk>,
+    summary: string,
+    chunk: TChunk,
+    areTrackedArtifactsReady: (trackedArtifactFiles: string[]) => boolean | Promise<boolean>,
+  ): Promise<boolean> {
+    return Promise.resolve(areTrackedArtifactsReady(context.trackedArtifactFiles)).then((artifactsReady) => {
+    if (context.trackedArtifactFiles.length > 0) {
+      return artifactsReady && !RunCompletionPolicy.isToolCallSummary(summary);
+    }
+    return artifactsReady &&
+      !RunCompletionPolicy.isToolCallSummary(summary) &&
+      RunCompletionPolicy.hasAssistantFinalMessage(chunk);
+    });
+  }
+
+  public static shouldStopForChunk<TChunk>(
+    context: ExecutionContext<TChunk>,
+    params: AgentRuntimeRunOptions<TChunk>,
+    chunk: TChunk,
+    areTrackedArtifactsReady: (trackedArtifactFiles: string[]) => boolean | Promise<boolean>,
+  ): Promise<boolean> {
+    const summary = (params.summarizeChunk ?? AgentMessageService.summarizeAgentChunk)(chunk);
+    if (typeof summary !== "string") return Promise.resolve(false);
+    return Promise.resolve(areTrackedArtifactsReady(context.trackedArtifactFiles)).then((artifactsReady) => {
+      if (context.trackedArtifactFiles.length > 0) {
+        return artifactsReady && !RunCompletionPolicy.isToolCallSummary(summary);
+      }
+      return artifactsReady &&
+        !RunCompletionPolicy.isToolCallSummary(summary) &&
+        RunCompletionPolicy.hasAssistantFinalMessage(chunk);
+    });
+  }
+
+  public static logRunSummary<TChunk>(
+    context: ExecutionContext<TChunk>,
+    summary: string,
+    elapsedMs: number,
+    runLogger: (message: string) => void,
+  ): void {
+    if (summary.startsWith("Tool call:")) {
+      if (context.pendingToolCall) {
+        runLogger(RunSummaryFormatter.formatRunStep(
+          context.pendingToolCall.summary,
+          context.pendingToolCall.elapsedMs,
+        ));
+      }
+      context.pendingToolCall = { summary, elapsedMs };
+      return;
+    }
+    if (summary === context.lastLoggedSummary) return;
+
+    const formatted = context.pendingToolCall
+      ? RunSummaryFormatter.formatMergedRunStep(context.pendingToolCall.summary, summary, elapsedMs)
+      : RunSummaryFormatter.formatRunStep(summary, elapsedMs);
+    runLogger(formatted);
+    context.pendingToolCall = undefined;
+    context.lastLoggedSummary = summary;
+  }
+}

package/src/runtime/execution/agentRunState.ts

@@ -0,0 +1,66 @@
+import type { AgentWorkspaceState } from "../../state/workspaceState.js";
+export interface PendingToolCall {
+  summary: string;
+  elapsedMs: number;
+}
+
+export interface RetryState {
+  malformedRetryCount: number;
+  incompleteRetryCount: number;
+  emptyRetryCount: number;
+  idleTimeoutRetryCount: number;
+  transientModelRetryCount: number;
+  malformedToolCallMaxRetries: number;
+  incompleteRunMaxRetries: number;
+  emptyRunMaxRetries: number;
+  idleTimeoutMaxRetries: number;
+  transientModelMaxRetries: number;
+}
+
+export interface ExecutionContext<TChunk> {
+  run: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>;
+  effectivePrompt: string;
+  trackedArtifactFiles: string[];
+  trackedPaths: string[];
+  requiredArtifactPaths: string[];
+  runInput: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["input"];
+  runConfig: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["config"];
+  pendingToolCall: PendingToolCall | undefined;
+  lastLoggedSummary: string;
+  lastStepCount: number;
+  lastSummary: string;
+}
+
+export class AgentRunStateFactory {
+  public static createRetryState(
+    hasTrackedArtifacts: boolean,
+    params: {
+      malformedToolCallMaxRetries?: number;
+      incompleteRunMaxRetries?: number;
+      emptyRunMaxRetries?: number;
+      idleTimeoutMaxRetries?: number;
+    },
+    defaults: {
+      incompleteRunMaxRetries?: number;
+      emptyRunMaxRetries?: number;
+      malformedToolCallMaxRetries?: number;
+      idleTimeoutMaxRetries?: number;
+    },
+  ): RetryState {
+    return {
+      malformedRetryCount: 0,
+      incompleteRetryCount: 0,
+      emptyRetryCount: 0,
+      idleTimeoutRetryCount: 0,
+      transientModelRetryCount: 0,
+      malformedToolCallMaxRetries:
+        params.malformedToolCallMaxRetries ?? defaults.malformedToolCallMaxRetries ?? 2,
+      incompleteRunMaxRetries:
+        params.incompleteRunMaxRetries ?? defaults.incompleteRunMaxRetries ?? (hasTrackedArtifacts ? 2 : 0),
+      emptyRunMaxRetries: params.emptyRunMaxRetries ?? defaults.emptyRunMaxRetries ?? 2,
+      idleTimeoutMaxRetries: params.idleTimeoutMaxRetries ?? defaults.idleTimeoutMaxRetries ?? 1,
+      transientModelMaxRetries:
+        Number(process.env.LLM_TRANSIENT_RETRIES) >= 0 ? Number(process.env.LLM_TRANSIENT_RETRIES) : 0,
+    };
+  }
+}