@botbotgo/runtime 1.0.0

package/src/runtime/runtimeService.ts

@@ -0,0 +1,205 @@
+import type { DrainAgentStreamResult } from "./stream/agentStream.js";
+import {
+  type AgentRuntimeRunOptions,
+  AgentRunExecutor,
+} from "./execution/agentRunExecutor.js";
+import { AgentRuntimeFactory } from "./bootstrap/runtimeFactory.js";
+import { AgentRuntimeModuleInitializer } from "./bootstrap/runtimeModuleInitializer.js";
+import type { CreateAgentToolMiddlewareOptions } from "./middleware/index.js";
+import type {
+  AgentWorkspaceState,
+  CreateAgentWorkspaceStateOptions,
+} from "../state/workspaceState.js";
+import type { AgentBackendConfig, OpenAILocalAgentService } from "./providers/index.js";
+import {
+  AgentRuntimeEventPublisher,
+  type AgentEventBus,
+  type AgentEventListener,
+} from "./events/eventPublisher.js";
+import type { ResolvedAgentRuntimeConfig } from "../config/index.js";
+import type { HumanLoopService, HumanLoopToolPolicy } from "./human-loop/humanLoop.js";
+
+export interface CreateAgentRuntimeOptions
+  extends Omit<CreateAgentWorkspaceStateOptions, "todosLogger" | "events">,
+    Omit<
+      CreateAgentToolMiddlewareOptions,
+      "persistTodos" | "createMiddleware" | "ToolMessage" | "rootDir" | "events"
+    > {
+  eventBus?: AgentEventBus;
+  humanLoop?: HumanLoopService;
+  humanLoopToolPolicy?: HumanLoopToolPolicy;
+  configDir?: string;
+  systemPrompt?: string;
+  toolConfigPath?: string;
+  modelConfigPath?: string;
+  modelCheckConnectivity?: boolean;
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  backend?: AgentBackendConfig;
+  todosLogger?: CreateAgentWorkspaceStateOptions["todosLogger"];
+  runLogger?: (message: string) => void;
+  incompleteRunMaxRetries?: number;
+  emptyRunMaxRetries?: number;
+  malformedToolCallMaxRetries?: number;
+  idleTimeoutMaxRetries?: number;
+  heartbeatIntervalMs?: number;
+  idleTimeoutMs?: number;
+  artifactValidator?: (context: {
+    rootDir: string;
+    trackedArtifactFiles: string[];
+    requiredArtifactPaths: string[];
+  }) => boolean | Promise<boolean>;
+}
+
+export interface CreateAgentRuntimeFrameworkOptions extends CreateAgentRuntimeOptions {
+  memoryConfigPath?: string;
+  forceInitializeModules?: boolean;
+}
+
+export interface AgentRuntime {
+  events: AgentEventBus;
+  eventListener: AgentEventListener | undefined;
+  runtimeConfig: ResolvedAgentRuntimeConfig;
+  middleware: unknown;
+  workspace: AgentWorkspaceState;
+  agent: {
+    stream: (input: unknown, options: { configurable: { thread_id: string }; streamMode: "values" }) => Promise<AsyncIterable<unknown>>;
+  };
+  prepareRun: AgentWorkspaceState["prepareRun"];
+  close(): Promise<void>;
+  runStream<TChunk>(params: {
+    prompt: string;
+    createStream: (context: {
+      input: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["input"];
+      config: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["config"];
+    }) => Promise<AsyncIterable<TChunk>> | AsyncIterable<TChunk>;
+  } & AgentRuntimeRunOptions<TChunk>): Promise<DrainAgentStreamResult<TChunk>>;
+  run(prompt: string, options?: AgentRuntimeRunOptions<unknown>): Promise<DrainAgentStreamResult<unknown>>;
+}
+
+export class AgentRuntimeService implements AgentRuntime {
+  public readonly events: AgentEventBus;
+  public readonly runtimeConfig: ResolvedAgentRuntimeConfig;
+  public readonly middleware: unknown;
+  public readonly workspace: AgentWorkspaceState;
+  public readonly agent: AgentRuntime["agent"];
+  public readonly prepareRun: AgentWorkspaceState["prepareRun"];
+
+  private readonly eventsPublisher: AgentRuntimeEventPublisher;
+  private readonly runtimeAgent: OpenAILocalAgentService;
+  private readonly runExecutor: AgentRunExecutor;
+  private eventListenerUnsubscribe?: () => void;
+  private currentEventListener?: AgentEventListener;
+
+  public constructor(params: {
+    rootDir: string;
+    runLogger: (message: string) => void;
+    events: AgentRuntimeEventPublisher;
+    runtimeConfig: ResolvedAgentRuntimeConfig;
+    middleware: unknown;
+    workspace: AgentWorkspaceState;
+    runtimeAgent: OpenAILocalAgentService;
+    defaultIncompleteRunMaxRetries?: number;
+    defaultEmptyRunMaxRetries?: number;
+    defaultMalformedToolCallMaxRetries?: number;
+    defaultIdleTimeoutMaxRetries?: number;
+    defaultHeartbeatIntervalMs?: number;
+    defaultIdleTimeoutMs?: number;
+    artifactValidator?: CreateAgentRuntimeOptions["artifactValidator"];
+  }) {
+    this.eventsPublisher = params.events;
+    this.events = params.events.bus;
+    this.runtimeConfig = params.runtimeConfig;
+    this.middleware = params.middleware;
+    this.workspace = params.workspace;
+    this.runtimeAgent = params.runtimeAgent;
+    this.agent = {
+      stream: (input, options) => {
+        const current = this.runtimeAgent.agent as AgentRuntime["agent"];
+        return current.stream(input, options);
+      },
+    };
+    this.prepareRun = params.workspace.prepareRun.bind(params.workspace);
+    this.runExecutor = new AgentRunExecutor({
+      rootDir: params.rootDir,
+      workspace: params.workspace,
+      events: params.events,
+      runLogger: params.runLogger,
+      defaultIncompleteRunMaxRetries: params.defaultIncompleteRunMaxRetries,
+      defaultEmptyRunMaxRetries: params.defaultEmptyRunMaxRetries,
+      defaultMalformedToolCallMaxRetries: params.defaultMalformedToolCallMaxRetries,
+      defaultIdleTimeoutMaxRetries: params.defaultIdleTimeoutMaxRetries,
+      defaultHeartbeatIntervalMs: params.defaultHeartbeatIntervalMs,
+      defaultIdleTimeoutMs: params.defaultIdleTimeoutMs,
+      artifactValidator: params.artifactValidator,
+    });
+  }
+
+  public get eventListener(): AgentEventListener | undefined {
+    return this.currentEventListener;
+  }
+
+  public set eventListener(listener: AgentEventListener | undefined) {
+    this.eventListenerUnsubscribe?.();
+    this.eventListenerUnsubscribe = undefined;
+    this.currentEventListener = listener;
+    if (listener) {
+      this.eventListenerUnsubscribe = this.events.subscribe(listener);
+    }
+  }
+
+  public static async create(options: CreateAgentRuntimeOptions): Promise<AgentRuntimeService> {
+    return AgentRuntimeFactory.create(options);
+  }
+
+  public async close(): Promise<void> {
+    this.eventListener = undefined;
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.close.start",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.runtime",
+    });
+    await this.runtimeAgent.close();
+    this.eventsPublisher.emit({
+      name: "agent.runtime2.close.done",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.runtime",
+    });
+  }
+
+  public runStream<TChunk>(
+    params: {
+      prompt: string;
+      createStream: (context: {
+        input: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["input"];
+        config: Awaited<ReturnType<AgentWorkspaceState["prepareRun"]>>["config"];
+      }) => Promise<AsyncIterable<TChunk>> | AsyncIterable<TChunk>;
+    } & AgentRuntimeRunOptions<TChunk>,
+  ): Promise<DrainAgentStreamResult<TChunk>> {
+    return this.runExecutor.runStream(params);
+  }
+
+  public run(prompt: string, options: AgentRuntimeRunOptions<unknown> = {}): Promise<DrainAgentStreamResult<unknown>> {
+    return this.runStream({
+      prompt,
+      ...options,
+      createStream: ({ input, config }) => this.agent.stream(input, { ...config, streamMode: "values" }),
+    });
+  }
+}
+
+export async function initializeAgentRuntimeModules(
+  options: CreateAgentRuntimeFrameworkOptions,
+): Promise<void> {
+  await AgentRuntimeModuleInitializer.initialize(options);
+}
+
+export async function createAgentRuntime2(
+  options: CreateAgentRuntimeFrameworkOptions,
+): Promise<AgentRuntimeService> {
+  await initializeAgentRuntimeModules(options);
+  return AgentRuntimeService.create(options);
+}
+
+export type { AgentRuntimeRunOptions } from "./execution/agentRunExecutor.js";

package/src/runtime/stream/agentMessages.ts

@@ -0,0 +1,72 @@
+import { MessageSummary } from "./messageSummary.js";
+
+export interface AgentMessageLike extends Record<string, unknown> {
+  id?: unknown;
+  role?: unknown;
+  type?: unknown;
+  content?: unknown;
+  kwargs?: {
+    content?: unknown;
+    tool_calls?: Array<{ name?: string; function?: { name?: string; arguments?: unknown }; args?: unknown }>;
+  };
+  tool_calls?: Array<{ name?: string; function?: { name?: string; arguments?: unknown }; args?: unknown }>;
+}
+
+export interface SummarizeAgentChunkOptions {
+  emptyLabel?: string;
+  toolCallLabel?: string;
+  toolResultLabel?: string;
+  toolResultUnit?: string;
+  messageLabel?: string;
+  userLabel?: string;
+  fallbackLabel?: string;
+  textPreviewLength?: number;
+}
+
+const DEFAULT_SUMMARY_OPTIONS: Required<SummarizeAgentChunkOptions> = {
+  emptyLabel: "Waiting...",
+  toolCallLabel: "Tool call",
+  toolResultLabel: "Tool result",
+  toolResultUnit: "chars",
+  messageLabel: "Message",
+  userLabel: "User message received",
+  fallbackLabel: "",
+  textPreviewLength: 60,
+};
+
+export class AgentMessageService {
+  public static getAgentMessages(chunk: unknown): AgentMessageLike[] {
+    const state = chunk as { messages?: unknown[]; state?: { messages?: unknown[] } };
+    return (state?.messages ?? state?.state?.messages ?? []) as AgentMessageLike[];
+  }
+
+  public static summarizeAgentChunk(
+    chunk: unknown,
+    options: SummarizeAgentChunkOptions = {},
+  ): string | null {
+    const config = { ...DEFAULT_SUMMARY_OPTIONS, ...options };
+    const messages = AgentMessageService.getAgentMessages(chunk);
+    if (messages.length === 0) return config.emptyLabel;
+
+    const last = messages[messages.length - 1];
+    const previous = messages.length > 1 ? messages[messages.length - 2] : undefined;
+    const kwargs = last?.kwargs as AgentMessageLike["kwargs"] | undefined;
+    const idStr = Array.isArray(last?.id) ? last.id.join(" ") : String(last?.id ?? "");
+    const toolCalls = (last?.tool_calls ?? kwargs?.tool_calls) as AgentMessageLike["tool_calls"] | undefined;
+
+    if (MessageSummary.looksLikeStartPrompt(last)) return "Started run";
+    if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+      return MessageSummary.summarizeToolCall(toolCalls, config);
+    }
+    if (String(last?.role) === "user" || String(last?.role) === "human") return "Started run";
+
+    const content = last?.content ?? kwargs?.content;
+    if (String(last?.type).includes("Tool") || String(last?.role) === "tool" || idStr.includes("ToolMessage")) {
+      return MessageSummary.summarizeToolResult(content, config);
+    }
+    if (typeof content === "string" && content.trim()) {
+      return MessageSummary.summarizeContextualMessage(content, previous);
+    }
+    return config.fallbackLabel || null;
+  }
+}

package/src/runtime/stream/agentStream.ts

@@ -0,0 +1,168 @@
+export interface AgentStreamSummaryEvent<TChunk> {
+  chunk: TChunk;
+  stepIndex: number;
+  elapsedMs: number;
+  summary: string;
+}
+
+export interface AgentStreamHeartbeatEvent {
+  elapsedMs: number;
+}
+
+export interface DrainAgentStreamOptions<TChunk> {
+  heartbeatIntervalMs?: number;
+  idleTimeoutMs?: number;
+  getNow?: () => number;
+  summarizeChunk?: (chunk: TChunk) => string | null | undefined;
+  onChunk?: (chunk: TChunk) => Promise<void> | void;
+  onSummary?: (event: AgentStreamSummaryEvent<TChunk>) => Promise<void> | void;
+  shouldStopOnSummary?: (event: AgentStreamSummaryEvent<TChunk>) => Promise<boolean> | boolean;
+  onHeartbeat?: (event: AgentStreamHeartbeatEvent) => Promise<void> | void;
+  shouldStop?: (chunk: TChunk) => Promise<boolean> | boolean;
+}
+
+export interface DrainAgentStreamResult<TChunk> {
+  lastChunk: TChunk | null;
+  lastSummary: string;
+  stepCount: number;
+  durationMs: number;
+  stoppedEarly: boolean;
+}
+
+export class AgentStreamService {
+  public static async drain<TChunk>(
+    stream: AsyncIterable<TChunk>,
+    options: DrainAgentStreamOptions<TChunk> = {},
+  ): Promise<DrainAgentStreamResult<TChunk>> {
+    const {
+      heartbeatIntervalMs = 5_000,
+      idleTimeoutMs,
+      getNow = () => Date.now(),
+      summarizeChunk,
+      onChunk,
+      onSummary,
+      shouldStopOnSummary,
+      onHeartbeat,
+      shouldStop,
+    } = options;
+
+    const startedAt = getNow();
+    let lastChunk: TChunk | null = null;
+    let lastSummary = "";
+    let stepCount = 0;
+    let lastChunkTime = startedAt;
+    let lastHeartbeatTime = startedAt;
+    let stoppedEarly = false;
+    let stopRequested = false;
+
+    const heartbeatInterval = onHeartbeat
+      ? setInterval(() => {
+          if (getNow() - lastHeartbeatTime >= heartbeatIntervalMs) {
+            void onHeartbeat({ elapsedMs: getNow() - startedAt });
+            lastHeartbeatTime = getNow();
+          }
+        }, heartbeatIntervalMs)
+      : null;
+
+    const iterator = stream[Symbol.asyncIterator]();
+    try {
+      while (true) {
+        const { value: chunk, done } = await nextWithIdleTimeout(
+          iterator,
+          idleTimeoutMs,
+          getNow() - lastChunkTime,
+        );
+        if (done) break;
+
+        lastChunk = chunk;
+        lastChunkTime = getNow();
+        lastHeartbeatTime = lastChunkTime;
+
+        await onChunk?.(chunk);
+
+        const summary = summarizeChunk?.(chunk);
+        if (summary && summary !== lastSummary) {
+          lastSummary = summary;
+          stepCount += 1;
+          const summaryEvent = {
+            chunk,
+            stepIndex: stepCount,
+            elapsedMs: getNow() - startedAt,
+            summary,
+          };
+          await onSummary?.(summaryEvent);
+          if (await shouldStopOnSummary?.(summaryEvent)) {
+            stoppedEarly = true;
+            stopRequested = true;
+            await returnIteratorWithTimeout(iterator, 1_500);
+            break;
+          }
+        }
+
+        if (await shouldStop?.(chunk)) {
+          stoppedEarly = true;
+          stopRequested = true;
+          await returnIteratorWithTimeout(iterator, 1_500);
+          break;
+        }
+      }
+    } finally {
+      if (heartbeatInterval) clearInterval(heartbeatInterval);
+      if (!stopRequested) {
+        await returnIteratorWithTimeout(iterator, 1_500);
+      }
+    }
+
+    return {
+      lastChunk,
+      lastSummary,
+      stepCount,
+      durationMs: getNow() - startedAt,
+      stoppedEarly,
+    };
+  }
+}
+
+async function returnIteratorWithTimeout<TChunk>(
+  iterator: AsyncIterator<TChunk>,
+  timeoutMs: number,
+): Promise<void> {
+  if (typeof iterator.return !== "function") {
+    return;
+  }
+
+  await Promise.race([
+    iterator.return(),
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]).catch(() => {});
+}
+
+async function nextWithIdleTimeout<TChunk>(
+  iterator: AsyncIterator<TChunk>,
+  idleTimeoutMs: number | undefined,
+  elapsedSinceLastChunkMs: number,
+): Promise<IteratorResult<TChunk>> {
+  if (!idleTimeoutMs || idleTimeoutMs <= 0) {
+    return iterator.next();
+  }
+
+  const remainingMs = Math.max(1, idleTimeoutMs - elapsedSinceLastChunkMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      iterator.next(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(`Agent stream idle timeout after ${idleTimeoutMs}ms without new output`));
+        }, remainingMs);
+        if (timer && typeof timer.unref === "function") {
+          timer.unref();
+        }
+      }),
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/runtime/stream/messageSummary.ts

@@ -0,0 +1,164 @@
+import type { AgentMessageLike, SummarizeAgentChunkOptions } from "./agentMessages.js";
+
+export class MessageSummary {
+  public static looksLikeStartPrompt(message: AgentMessageLike | undefined): boolean {
+    const content = typeof message?.content === "string" ? message.content : "";
+    if (String(message?.role) !== "user" && String(message?.role) !== "human") {
+      return false;
+    }
+    return content.includes("Tool-call rules:") || content.includes("Continue in the current thread");
+  }
+
+  public static summarizeToolCall(
+    toolCalls: NonNullable<AgentMessageLike["tool_calls"]>,
+    config: Required<SummarizeAgentChunkOptions>,
+  ): string | null {
+    const labels = toolCalls.map((tool) => this.describeToolCall(tool));
+    if (labels.every((label) => label === "update todo list")) {
+      return null;
+    }
+    return labels.length === 1
+      ? `${config.toolCallLabel}: ${labels[0]}`
+      : `${config.toolCallLabel}: ${labels.join(", ")}`;
+  }
+
+  public static summarizeToolResult(
+    content: unknown,
+    config: Required<SummarizeAgentChunkOptions>,
+  ): string | null {
+    if (typeof content !== "string" || !content.trim()) {
+      return `${config.toolResultLabel} (empty)`;
+    }
+
+    const text = this.sanitizePreview(content);
+    if (text.startsWith("Successfully wrote to")) {
+      return `Saved file${this.extractQuotedPath(text) ? ` to ${this.extractQuotedPath(text)}` : ""}`;
+    }
+    if (text.includes("Too Many Requests")) return "Rate limited, continuing";
+    if (text.includes("Updated todo list to")) return null;
+    if (this.looksLikeFileListing(text)) return "Checked workspace files";
+    if (text.startsWith("Usage:")) return "Command returned a usage error";
+    if (text.startsWith("OK:")) return "Command reported success";
+    if (text.includes("[Command succeeded")) return "Command completed";
+
+    const preview = text.slice(0, config.textPreviewLength);
+    return `${config.toolResultLabel}: ${preview}${text.length > config.textPreviewLength ? "…" : ""}`;
+  }
+
+  public static summarizeContextualMessage(
+    content: string,
+    previous: AgentMessageLike | undefined,
+  ): string | null {
+    const text = this.sanitizePreview(content);
+    if (!text || text.includes("Updated todo list to") || this.looksLikeInternalPlanning(text)) {
+      return null;
+    }
+    if (text.startsWith("✅")) return "Run completed";
+    if (text.startsWith("Successfully wrote to")) {
+      return `Saved file${this.extractQuotedPath(text) ? ` to ${this.extractQuotedPath(text)}` : ""}`;
+    }
+    if (text.includes("Too Many Requests")) return "Rate limited, continuing";
+    if (this.looksLikeFileListing(text)) return "Checked workspace files";
+    if (text.startsWith("<!-- <!DOCTYPE HTML") || text.startsWith("<!DOCTYPE HTML") || text.startsWith("<html")) {
+      return "Reviewed generated content";
+    }
+    if (this.looksLikeSkillFrontMatter(content)) return "Loaded instructions";
+    if (text.startsWith("OK:")) return "Command reported success";
+    if (this.isToolMessage(previous) && this.looksLikeFileDump(content)) return "Reviewed file contents";
+    return null;
+  }
+
+  private static describeToolCall(tool: NonNullable<AgentMessageLike["tool_calls"]>[number]): string {
+    const name = tool?.name ?? tool?.function?.name ?? "?";
+    const normalizedName = this.humanizeToolName(name);
+    const args = this.normalizeToolCallArgs(tool);
+
+    if ((name === "read_file" || name === "write_file" || name === "edit_file") && typeof args.file_path === "string") {
+      return `${normalizedName} ${this.formatPath(args.file_path)}`;
+    }
+    if ((name === "read_file" || name === "write_file" || name === "edit_file") && typeof args.path === "string") {
+      return `${normalizedName} ${this.formatPath(args.path)}`;
+    }
+    if (name === "execute" && typeof args.command === "string") {
+      return `${normalizedName} ${this.truncateText(args.command, 72)}`;
+    }
+    return name === "write_todos" ? "update todo list" : normalizedName;
+  }
+
+  private static normalizeToolCallArgs(
+    tool: NonNullable<AgentMessageLike["tool_calls"]>[number],
+  ): Record<string, unknown> {
+    const directArgs = tool?.args;
+    if (directArgs && typeof directArgs === "object") {
+      return directArgs as Record<string, unknown>;
+    }
+    const rawArguments = tool?.function?.arguments;
+    if (typeof rawArguments === "string") {
+      try {
+        const parsed = JSON.parse(rawArguments) as unknown;
+        if (parsed && typeof parsed === "object") {
+          return parsed as Record<string, unknown>;
+        }
+      } catch {}
+    } else if (rawArguments && typeof rawArguments === "object") {
+      return rawArguments as Record<string, unknown>;
+    }
+    return {};
+  }
+
+  private static sanitizePreview(content: string): string {
+    return content.replace(/\s+/g, " ").trim();
+  }
+
+  private static humanizeToolName(name: string): string {
+    switch (name) {
+      case "read_file": return "read file";
+      case "write_file": return "write file";
+      case "edit_file": return "edit file";
+      case "write_todos": return "update todo list";
+      case "ls": return "inspect files";
+      default: return name.replace(/_/g, " ");
+    }
+  }
+
+  private static extractQuotedPath(text: string): string | null {
+    const match = text.match(/'([^']+)'/);
+    return match?.[1] ? this.formatPath(match[1]) : null;
+  }
+
+  private static truncateText(text: string, maxLength: number): string {
+    return text.length > maxLength ? `${text.slice(0, maxLength - 1)}...` : text;
+  }
+
+  private static formatPath(path: string): string {
+    const normalized = path.replace(/\\/g, "/");
+    for (const marker of ["/skills/", "/output/", "/config/", "/.agent/"]) {
+      const index = normalized.indexOf(marker);
+      if (index >= 0) return normalized.slice(index + 1);
+    }
+    const segments = normalized.split("/").filter(Boolean);
+    return segments.length <= 3 ? normalized : segments.slice(-3).join("/");
+  }
+
+  private static looksLikeFileListing(text: string): boolean {
+    return text.includes("\n[file]") || text.includes("\n... truncated ") || /^[./\w-]+\n[\w./@-]+/m.test(text);
+  }
+
+  private static looksLikeInternalPlanning(text: string): boolean {
+    return text.startsWith("<think") || text.includes("I should") || text.includes("I'll ");
+  }
+
+  private static looksLikeSkillFrontMatter(content: string): boolean {
+    return content.includes("## Skills") || content.includes("### Available skills");
+  }
+
+  private static isToolMessage(message: AgentMessageLike | undefined): boolean {
+    if (!message) return false;
+    const idStr = Array.isArray(message.id) ? message.id.join(" ") : String(message.id ?? "");
+    return String(message.role) === "tool" || String(message.type).includes("Tool") || idStr.includes("ToolMessage");
+  }
+
+  private static looksLikeFileDump(content: string): boolean {
+    return content.includes("\n") && !content.includes("Tool-call rules:") && !content.startsWith("{\"messages\"");
+  }
+}

package/src/runtime/stream/runArtifacts.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+
+export class RunArtifactService {
+  public static inferPromptArtifactPaths(prompt: string): string[] {
+    const matches = [...prompt.matchAll(/\b(?:save(?: it)? to|write to)\s+([^\s"'`]+?\.[a-z0-9]+)/gi)];
+    return matches.map((match) => match[1]).filter(Boolean);
+  }
+
+  public static resolveTrackedArtifactFiles(
+    rootDir: string,
+    artifactFiles: Record<string, string>,
+    prompt: string,
+  ): string[] {
+    const configuredArtifacts = Object.values(artifactFiles);
+    if (configuredArtifacts.length > 0) {
+      return configuredArtifacts;
+    }
+
+    return RunArtifactService.inferPromptArtifactPaths(prompt).map((file) => resolve(rootDir, file));
+  }
+
+  public static buildTrackedPaths(
+    rootDir: string,
+    runStateFile: string,
+    todosFile: string,
+    trackedArtifactFiles: string[],
+  ): string[] {
+    return [runStateFile, todosFile, ...trackedArtifactFiles]
+      .map((file) => relative(rootDir, file))
+      .filter(Boolean);
+  }
+
+  public static async resetTrackedArtifactsForFreshRun(
+    previousStatus: string | undefined,
+    trackedArtifactFiles: string[],
+  ): Promise<void> {
+    if (previousStatus === "running") {
+      return;
+    }
+
+    await Promise.all(
+      trackedArtifactFiles
+        .filter((file) => existsSync(file))
+        .map((file) => unlink(file).catch(() => {})),
+    );
+  }
+
+  public static areArtifactsUsable(trackedArtifactFiles: string[]): boolean {
+    return trackedArtifactFiles.length === 0 ||
+      trackedArtifactFiles.every((file) => RunArtifactService.isArtifactUsable(file));
+  }
+
+  private static isArtifactUsable(filePath: string): boolean {
+    if (!existsSync(filePath)) {
+      return false;
+    }
+
+    const stat = statSync(filePath, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile() || stat.size <= 0) {
+      return false;
+    }
+
+    if (!/\.html?$/i.test(filePath)) {
+      return true;
+    }
+
+    const text = readFileSync(filePath, "utf8").trim().toLowerCase();
+    return text.includes("<html") || text.includes("<!doctype html");
+  }
+}