@botbotgo/runtime 1.0.0

package/src/state/index.ts

@@ -0,0 +1,19 @@
+export { createTodoPersister, normalizeTodos, TodoPersister } from "./todos.js";
+export type {
+  CreateTodoPersisterOptions,
+  NormalizedTodo,
+} from "./todos.js";
+
+export { createAgentRunStateStore, AgentRunStateStore } from "./runState.js";
+export type {
+  AgentRunState,
+  AgentRunStatus,
+  CreateAgentRunStateStoreOptions,
+  UpdateAgentRunStateOptions,
+} from "./runState.js";
+
+export { createAgentWorkspaceState, AgentWorkspaceStateManager } from "./workspaceState.js";
+export type {
+  CreateAgentWorkspaceStateOptions,
+  AgentWorkspaceState,
+} from "./workspaceState.js";

package/src/state/runState.ts

@@ -0,0 +1,84 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export type AgentRunStatus = "running" | "completed" | "failed";
+
+export interface AgentRunState {
+  prompt: string;
+  threadId: string;
+  status: AgentRunStatus;
+  startedAt: string;
+  updatedAt: string;
+  stepCount: number;
+  lastSummary: string;
+  artifacts: Record<string, unknown>;
+}
+
+export interface CreateAgentRunStateStoreOptions {
+  filePath: string;
+  getArtifacts?: () => Record<string, unknown>;
+}
+
+export interface UpdateAgentRunStateOptions {
+  prompt: string;
+  threadId: string;
+  previousState?: AgentRunState | null;
+  stepCount: number;
+  lastSummary: string;
+  status: AgentRunStatus;
+  updatedAt?: string;
+}
+
+export class AgentRunStateStore {
+  public readonly filePath: string;
+  private readonly getArtifacts: () => Record<string, unknown>;
+
+  public constructor(options: CreateAgentRunStateStoreOptions) {
+    this.filePath = options.filePath;
+    this.getArtifacts = options.getArtifacts ?? (() => ({}));
+  }
+
+  public async read(): Promise<AgentRunState | null> {
+    try {
+      return JSON.parse(await readFile(this.filePath, "utf8")) as AgentRunState;
+    } catch {
+      return null;
+    }
+  }
+
+  public async write(state: AgentRunState): Promise<void> {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(this.filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  }
+
+  public async update(params: UpdateAgentRunStateOptions): Promise<AgentRunState> {
+    const now = params.updatedAt ?? new Date().toISOString();
+    const state: AgentRunState = {
+      prompt: params.prompt,
+      threadId: params.threadId,
+      status: params.status,
+      startedAt: params.previousState?.status === "running"
+        ? params.previousState.startedAt
+        : now,
+      updatedAt: now,
+      stepCount: params.stepCount,
+      lastSummary: params.lastSummary,
+      artifacts: this.getArtifacts(),
+    };
+    await this.write(state);
+    return state;
+  }
+
+  public buildResumePrompt(basePrompt: string, previousState: AgentRunState | null, resumeHint: string): string {
+    if (previousState?.status !== "running") return basePrompt;
+    return `${basePrompt}\n\n${resumeHint}`;
+  }
+
+  public getThreadId(previousState: AgentRunState | null, fallbackThreadId: string): string {
+    return previousState?.status === "running" ? previousState.threadId : fallbackThreadId;
+  }
+}
+
+export function createAgentRunStateStore(options: CreateAgentRunStateStoreOptions) {
+  return new AgentRunStateStore(options);
+}

package/src/state/todos.ts

@@ -0,0 +1,59 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export interface NormalizedTodo {
+  content: unknown;
+  status: string;
+}
+
+export interface CreateTodoPersisterOptions {
+  filePath: string;
+  logger?: (message: string) => void;
+}
+
+export function normalizeTodos(todos: unknown): NormalizedTodo[] {
+  return TodoPersister.normalize(todos);
+}
+
+export class TodoPersister {
+  private readonly filePath: string;
+  private readonly logger: (message: string) => void;
+  private lastPersistedJson = "";
+
+  public constructor(options: CreateTodoPersisterOptions) {
+    this.filePath = options.filePath;
+    this.logger = options.logger ?? (() => {});
+  }
+
+  public static normalize(todos: unknown): NormalizedTodo[] {
+    if (!Array.isArray(todos) || todos.length === 0) return [];
+
+    return todos
+      .map((todo) => {
+        if (!todo || typeof todo !== "object" || !("content" in todo)) return null;
+        return {
+          content: (todo as { content: unknown }).content,
+          status: (todo as { status?: string }).status ?? "pending",
+        };
+      })
+      .filter((todo): todo is NormalizedTodo => todo !== null);
+  }
+
+  public async persist(todos: unknown): Promise<void> {
+    const normalized = TodoPersister.normalize(todos);
+    if (normalized.length === 0) return;
+
+    const nextJson = JSON.stringify(normalized, null, 2);
+    if (nextJson === this.lastPersistedJson) return;
+    this.lastPersistedJson = nextJson;
+
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(this.filePath, nextJson, "utf8");
+    this.logger(`[todos] persisted ${normalized.length} item(s) -> ${this.filePath}`);
+  }
+}
+
+export function createTodoPersister(options: CreateTodoPersisterOptions) {
+  const persister = new TodoPersister(options);
+  return persister.persist.bind(persister);
+}

package/src/state/workspaceRunSession.ts

@@ -0,0 +1,96 @@
+import type { AgentRunState, AgentRunStateStore } from "./runState.js";
+import type { AgentRuntimeEventPublisher } from "../runtime/events/eventPublisher.js";
+
+export interface PreparedWorkspaceRun {
+  previousState: AgentRunState | null;
+  threadId: string;
+  config: {
+    configurable: {
+      thread_id: string;
+    };
+  };
+  input: {
+    messages: Array<{
+      role: "user";
+      content: string;
+    }>;
+  };
+  start(): Promise<void>;
+  update(stepCount: number, lastSummary: string): Promise<void>;
+  finish(stepCount: number, lastSummary: string): Promise<void>;
+}
+
+export class WorkspaceRunSessionFactory {
+  public static create(params: {
+    prompt: string;
+    threadId: string;
+    previousState: AgentRunState | null;
+    resumeHint: string;
+    runState: AgentRunStateStore;
+    events?: AgentRuntimeEventPublisher;
+    isCompleted: () => boolean;
+  }): PreparedWorkspaceRun {
+    return {
+      previousState: params.previousState,
+      threadId: params.threadId,
+      config: { configurable: { thread_id: params.threadId } },
+      input: {
+        messages: [{
+          role: "user",
+          content: params.runState.buildResumePrompt(params.prompt, params.previousState, params.resumeHint),
+        }],
+      },
+      start: async () => {
+        await params.runState.update({
+          prompt: params.prompt,
+          threadId: params.threadId,
+          stepCount: 0,
+          lastSummary: "",
+          status: "running",
+          previousState: params.previousState,
+        });
+        params.events?.emit({
+          name: "agent.runtime2.workspace.run.start",
+          from: "agent-runtime2.workspace",
+          to: "agent-runtime2.state",
+          payload: { threadId: params.threadId, prompt: params.prompt },
+        });
+      },
+      update: async (stepCount, lastSummary) => {
+        await params.runState.update({
+          prompt: params.prompt,
+          threadId: params.threadId,
+          stepCount,
+          lastSummary,
+          status: "running",
+          previousState: params.previousState,
+          updatedAt: new Date().toISOString(),
+        });
+        params.events?.emit({
+          name: "agent.runtime2.workspace.run.update",
+          from: "agent-runtime2.workspace",
+          to: "agent-runtime2.state",
+          payload: { threadId: params.threadId, stepCount, lastSummary },
+        });
+      },
+      finish: async (stepCount, lastSummary) => {
+        const status = params.isCompleted() ? "completed" : "failed";
+        await params.runState.update({
+          prompt: params.prompt,
+          threadId: params.threadId,
+          stepCount,
+          lastSummary,
+          status,
+          previousState: params.previousState,
+          updatedAt: new Date().toISOString(),
+        });
+        params.events?.emit({
+          name: "agent.runtime2.workspace.run.finish",
+          from: "agent-runtime2.workspace",
+          to: "agent-runtime2.state",
+          payload: { threadId: params.threadId, stepCount, lastSummary, status },
+        });
+      },
+    };
+  }
+}

package/src/state/workspaceState.ts

@@ -0,0 +1,199 @@
+import { existsSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { AgentRunStateStore, createAgentRunStateStore, type AgentRunState } from "./runState.js";
+import { createTodoPersister } from "./todos.js";
+import { type AgentRuntimeEventPublisher } from "../runtime/events/eventPublisher.js";
+import { WorkspaceRunSessionFactory, type PreparedWorkspaceRun } from "./workspaceRunSession.js";
+
+export interface CreateAgentWorkspaceStateOptions {
+  rootDir: string;
+  artifacts?: Array<{ key: string; path: string }>;
+  stateDirName?: string;
+  legacyOutputState?: boolean;
+  todosLogger?: (message: string) => void;
+  events?: AgentRuntimeEventPublisher;
+}
+
+export interface AgentWorkspaceState {
+  stateDir: string;
+  todosFile: string;
+  runStateFile: string;
+  artifactFiles: Record<string, string>;
+  prepareRun(params: { prompt: string; fallbackThreadId?: string; resumeHint: string }): Promise<PreparedWorkspaceRun>;
+  readRunState(): Promise<AgentRunState | null>;
+  getThreadId(previousState: AgentRunState | null, fallbackThreadId: string): string;
+  buildResumePrompt(basePrompt: string, previousState: AgentRunState | null, resumeHint: string): string;
+  startRun(params: { prompt: string; threadId: string; previousState: AgentRunState | null }): Promise<void>;
+  updateRun(params: {
+    prompt: string;
+    threadId: string;
+    previousState: AgentRunState | null;
+    stepCount: number;
+    lastSummary: string;
+  }): Promise<void>;
+  finishRun(params: {
+    prompt: string;
+    threadId: string;
+    previousState: AgentRunState | null;
+    stepCount: number;
+    lastSummary: string;
+  }): Promise<void>;
+  resetForFreshRun(previousState: AgentRunState | null): Promise<void>;
+  persistTodos(todos: unknown): Promise<void>;
+}
+
+export class AgentWorkspaceStateManager implements AgentWorkspaceState {
+  public readonly stateDir: string;
+  public readonly todosFile: string;
+  public readonly runStateFile: string;
+  public readonly artifactFiles: Record<string, string>;
+
+  private readonly legacyOutputState: boolean;
+  private readonly legacyTodosFile: string;
+  private readonly legacyRunStateFile: string;
+  private readonly persistTodosHandler: (todos: unknown) => Promise<void>;
+  private readonly runState: AgentRunStateStore;
+  private readonly events?: AgentRuntimeEventPublisher;
+
+  public constructor(options: CreateAgentWorkspaceStateOptions) {
+    const {
+      rootDir,
+      artifacts = [],
+      stateDirName = ".agent",
+      legacyOutputState = true,
+      todosLogger,
+      events,
+    } = options;
+
+    this.stateDir = resolve(rootDir, stateDirName);
+    this.todosFile = resolve(this.stateDir, "todos.json");
+    this.runStateFile = resolve(this.stateDir, "run-state.json");
+    this.artifactFiles = Object.fromEntries(artifacts.map((artifact) => [artifact.key, resolve(rootDir, artifact.path)]));
+    this.legacyOutputState = legacyOutputState;
+    this.legacyTodosFile = resolve(rootDir, "output", "todos.json");
+    this.legacyRunStateFile = resolve(rootDir, "output", "run-state.json");
+    this.events = events;
+    this.persistTodosHandler = createTodoPersister({ filePath: this.todosFile, logger: todosLogger });
+    this.runState = createAgentRunStateStore({
+      filePath: this.runStateFile,
+      getArtifacts: () => ({
+        todosPath: this.todosFile,
+        todosPresent: existsSync(this.todosFile),
+        ...Object.fromEntries(
+          Object.entries(this.artifactFiles).flatMap(([key, file]) => [[`${key}Path`, file], [`${key}Present`, existsSync(file)]]),
+        ),
+      }),
+    });
+  }
+
+  public async prepareRun(params: {
+    prompt: string;
+    fallbackThreadId?: string;
+    resumeHint: string;
+  }): Promise<PreparedWorkspaceRun> {
+    const previousState = await this.runState.read();
+    const threadId = this.runState.getThreadId(previousState, params.fallbackThreadId ?? `t-${Date.now()}`);
+    this.events?.emit({
+      name: "agent.runtime2.workspace.prepare",
+      from: "agent-runtime2.runtime",
+      to: "agent-runtime2.workspace",
+      payload: { threadId, previousState },
+    });
+    await this.resetForFreshRun(previousState);
+    return WorkspaceRunSessionFactory.create({
+      prompt: params.prompt,
+      threadId,
+      previousState,
+      resumeHint: params.resumeHint,
+      runState: this.runState,
+      events: this.events,
+      isCompleted: this.isCompleted.bind(this),
+    });
+  }
+
+  public readRunState(): Promise<AgentRunState | null> {
+    return this.runState.read();
+  }
+
+  public getThreadId(previousState: AgentRunState | null, fallbackThreadId: string): string {
+    return this.runState.getThreadId(previousState, fallbackThreadId);
+  }
+
+  public buildResumePrompt(basePrompt: string, previousState: AgentRunState | null, resumeHint: string): string {
+    return this.runState.buildResumePrompt(basePrompt, previousState, resumeHint);
+  }
+
+  public async startRun(params: {
+    prompt: string;
+    threadId: string;
+    previousState: AgentRunState | null;
+  }): Promise<void> {
+    await this.runState.update({
+      prompt: params.prompt,
+      threadId: params.threadId,
+      stepCount: 0,
+      lastSummary: "",
+      status: "running",
+      previousState: params.previousState,
+    });
+  }
+
+  public async updateRun(params: {
+    prompt: string;
+    threadId: string;
+    previousState: AgentRunState | null;
+    stepCount: number;
+    lastSummary: string;
+  }): Promise<void> {
+    await this.runState.update({
+      prompt: params.prompt,
+      threadId: params.threadId,
+      stepCount: params.stepCount,
+      lastSummary: params.lastSummary,
+      status: "running",
+      previousState: params.previousState,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  public async finishRun(params: {
+    prompt: string;
+    threadId: string;
+    previousState: AgentRunState | null;
+    stepCount: number;
+    lastSummary: string;
+  }): Promise<void> {
+    await this.runState.update({
+      prompt: params.prompt,
+      threadId: params.threadId,
+      stepCount: params.stepCount,
+      lastSummary: params.lastSummary,
+      status: this.isCompleted() ? "completed" : "failed",
+      previousState: params.previousState,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  public async resetForFreshRun(previousState: AgentRunState | null): Promise<void> {
+    if (previousState?.status !== "running") return;
+    if (!this.legacyOutputState) {
+      await Promise.all([
+        unlink(this.legacyTodosFile).catch(() => {}),
+        unlink(this.legacyRunStateFile).catch(() => {}),
+      ]);
+    }
+  }
+
+  public async persistTodos(todos: unknown): Promise<void> {
+    await this.persistTodosHandler(todos);
+  }
+
+  private isCompleted(): boolean {
+    return Object.values(this.artifactFiles).every((file) => existsSync(file));
+  }
+}
+
+export function createAgentWorkspaceState(options: CreateAgentWorkspaceStateOptions): AgentWorkspaceState {
+  return new AgentWorkspaceStateManager(options);
+}

package/src/types/easynet-agent-common.d.ts

@@ -0,0 +1,62 @@
+declare module "@botbotgo/common/config" {
+  export function loadYamlFile<T = unknown>(filePath: string, options?: unknown): Promise<T | undefined>;
+  export function parseYamlContent<T = unknown>(content: string, options?: unknown): T;
+}
+
+declare module "@botbotgo/common/context" {
+  export interface AgentContext {
+    set<T>(token: symbol, value: T): void;
+    get<T>(token: symbol): T;
+    has(token: symbol): boolean;
+    tryGet<T>(token: symbol): T | undefined;
+  }
+
+  export const AgentContextTokens: Record<string, symbol>;
+  export function getDefaultAgentContext(): AgentContext;
+}
+
+declare module "@botbotgo/common/events" {
+  export interface AgentEvent<TPayload = unknown> {
+    id: string;
+    name: string;
+    from: string;
+    to: string;
+    at: string;
+    payload?: TPayload;
+  }
+
+  export type AgentEventListener = (event: AgentEvent) => void;
+
+  export interface AgentEventBus {
+    publish<TPayload = unknown>(event: Omit<AgentEvent<TPayload>, "id" | "at">): AgentEvent<TPayload>;
+    subscribe(listener: AgentEventListener): () => void;
+  }
+
+  export function createAgentEventBus(): AgentEventBus;
+}
+
+declare module "@botbotgo/common" {
+  export * from "@botbotgo/common/context";
+  export * from "@botbotgo/common/events";
+
+  export interface Runtime2EventDebugConfig {
+    run?: boolean;
+    workspace?: boolean;
+    toolCall?: boolean;
+    stream?: boolean;
+    close?: boolean;
+  }
+
+  export interface Runtime2EventRuntimeConfig {
+    debug?: Runtime2EventDebugConfig;
+  }
+
+  export interface Runtime2TreeEventListenerOptions {
+    writer?: (line: string) => void;
+    runtimeConfig?: Runtime2EventRuntimeConfig;
+  }
+
+  export function createRuntime2TreeEventListener(
+    options?: Runtime2TreeEventListenerOptions,
+  ): (event: AgentEvent) => void;
+}

package/src/types.ts

@@ -0,0 +1 @@
+export * from "./config/resources.js";

package/test/integration/runtime-live.integration.test.ts

@@ -0,0 +1,30 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { createAgentRuntime2 } from "../../src/index.ts";
+
+const shouldRun = process.env.RUN_REAL_RUNTIME2_INTEGRATION === "1";
+
+test("createAgentRuntime2 runs against a real model backend", { timeout: 180_000 }, async (t) => {
+  if (!shouldRun) {
+    t.skip("Set RUN_REAL_RUNTIME2_INTEGRATION=1 to run the live runtime integration test.");
+    return;
+  }
+
+  const rootDir = resolve(process.cwd(), "example");
+  const runtime = await createAgentRuntime2({
+    rootDir,
+    configDir: resolve(rootDir, "config"),
+    modelConfigPath: resolve(rootDir, "config/model.yaml"),
+    memoryConfigPath: resolve(rootDir, "config/memory.yaml"),
+    toolConfigPath: resolve(rootDir, "config/tool.yaml"),
+  });
+
+  try {
+    const result = await runtime.run("Reply with the single word READY.");
+    assert.equal(typeof result.text, "string");
+    assert.match(result.text.toUpperCase(), /READY/);
+  } finally {
+    await runtime.close();
+  }
+});