@modelprofile.com/flexharness-agent 6.0.0 → 7.0.0

package/ts_agent/index.ts

@@ -20,7 +20,6 @@ export {
 } from './smartagent.interfaces.js';
 export {
   AgentEventStoreConflictError,
-  FileAgentEventStore,
   InMemoryAgentEventStore,
   isAgentEventStoreV2,
   validateAgentEventArchiveV2,
@@ -67,7 +66,6 @@ export type {
   IAgentEventSnapshotV2,
   IAgentEventStore,
   IAgentEventStoreV2,
-  IFileAgentEventStoreOptions,
   TAgentEventArchive,
   TAgentEventSnapshot,
   TAgentEventStore,
@@ -117,3 +115,5 @@ export * from './tool.persistence.js';
 export * from './tool.adapter.js';
 export { tool, jsonSchema, stepCountIs } from 'ai';
 export { z } from 'zod';
+
+export { FileAgentEventStore, type IFileAgentEventStoreOptions } from './persistence.file.js';

package/ts_agent/persistence.file.ts

@@ -0,0 +1,232 @@
+import * as plugins from './plugins.node.js';
+import type { TAgentEvent } from './smartagent.events.js';
+import {
+  AgentEventStoreConflictError, clone, createSnapshot,
+  validateAgentEventArchiveV2, validateAgentEventSnapshotV2,
+  type IAgentEventArchiveV2, type IAgentEventStoreV2,
+  type TAgentEventArchive, type TAgentEventSnapshot,
+} from './smartagent.persistence.js';
+
+const SNAPSHOT_SCHEMA_VERSION = 2 as const;
+const ARCHIVE_SCHEMA_VERSION = 2 as const;
+
+export interface IFileAgentEventStoreOptions {
+  rootDir: string;
+  /** Maximum time spent waiting for another writer. Default: 10 seconds. */
+  lockTimeoutMs?: number;
+}
+
+const assertSessionId = (sessionId: string): void => {
+  if (!sessionId.trim()) throw new Error('Agent event store sessionId must not be empty.');
+};
+
+const decodeSnapshot = (value: unknown, sessionId: string): TAgentEventSnapshot => {
+  const snapshot = value as Partial<TAgentEventSnapshot>;
+  if (snapshot?.schemaVersion === SNAPSHOT_SCHEMA_VERSION) {
+    try {
+      return validateAgentEventSnapshotV2(value, sessionId);
+    } catch {
+      throw new Error(`Invalid agent event snapshot for session "${sessionId}".`);
+    }
+  }
+  if (
+    !snapshot
+    || snapshot.schemaVersion !== 1
+    || snapshot.sessionId !== sessionId
+    || !Number.isSafeInteger(snapshot.revision)
+    || (snapshot.revision ?? -1) < 1
+    || !Array.isArray(snapshot.events)
+  ) {
+    throw new Error(`Invalid agent event snapshot for session "${sessionId}".`);
+  }
+  return snapshot as TAgentEventSnapshot;
+};
+
+const decodeArchive = (
+  value: unknown,
+  sessionId: string,
+  archiveId: string,
+): TAgentEventArchive => {
+  const archive = value as Partial<TAgentEventArchive>;
+  if (archive?.schemaVersion === ARCHIVE_SCHEMA_VERSION) {
+    try {
+      return validateAgentEventArchiveV2(value, sessionId, archiveId);
+    } catch {
+      throw new Error(`Invalid agent event archive "${archiveId}" for session "${sessionId}".`);
+    }
+  }
+  if (
+    !archive
+    || archive.schemaVersion !== 1
+    || archive.sessionId !== sessionId
+    || archive.archiveId !== archiveId
+    || !Array.isArray(archive.events)
+  ) {
+    throw new Error(`Invalid agent event archive "${archiveId}" for session "${sessionId}".`);
+  }
+  return archive as TAgentEventArchive;
+};
+
+const sleep = async (milliseconds: number): Promise<void> => {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+};
+
+export class FileAgentEventStore implements IAgentEventStoreV2 {
+  public readonly eventSchemaVersion = 2 as const;
+  private readonly rootDir: string;
+  private readonly lockTimeoutMs: number;
+
+  constructor(options: IFileAgentEventStoreOptions) {
+    if (!options.rootDir.trim()) throw new Error('FileAgentEventStore rootDir must not be empty.');
+    this.rootDir = plugins.path.resolve(options.rootDir);
+    this.lockTimeoutMs = options.lockTimeoutMs ?? 10_000;
+    if (!Number.isSafeInteger(this.lockTimeoutMs) || this.lockTimeoutMs <= 0) {
+      throw new Error('lockTimeoutMs must be a positive integer.');
+    }
+  }
+
+  private sessionKey(sessionId: string): string {
+    assertSessionId(sessionId);
+    return plugins.crypto.createHash('sha256').update(sessionId).digest('hex');
+  }
+
+  private snapshotPath(sessionId: string): string {
+    return plugins.path.join(this.rootDir, 'sessions', `${this.sessionKey(sessionId)}.bin`);
+  }
+
+  private archivePath(sessionId: string, archiveId: string): string {
+    if (!archiveId.trim()) throw new Error('Agent event archiveId must not be empty.');
+    const archiveKey = plugins.crypto.createHash('sha256').update(archiveId).digest('hex');
+    return plugins.path.join(this.rootDir, 'archives', this.sessionKey(sessionId), `${archiveKey}.bin`);
+  }
+
+  private async readValue(filePath: string): Promise<unknown | undefined> {
+    try {
+      return plugins.v8.deserialize(await plugins.fs.readFile(filePath));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw error;
+    }
+  }
+
+  private async syncDirectory(directoryPath: string): Promise<void> {
+    const handle = await plugins.fs.open(directoryPath, 'r');
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  }
+
+  private async writeAtomic(filePath: string, value: unknown): Promise<void> {
+    const directoryPath = plugins.path.dirname(filePath);
+    await plugins.fs.mkdir(directoryPath, { recursive: true });
+    const temporaryPath = `${filePath}.${process.pid}.${plugins.crypto.randomUUID()}.tmp`;
+    let handle: Awaited<ReturnType<typeof plugins.fs.open>> | undefined;
+    try {
+      handle = await plugins.fs.open(temporaryPath, 'wx');
+      await handle.writeFile(plugins.v8.serialize(value));
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await plugins.fs.rename(temporaryPath, filePath);
+      await this.syncDirectory(directoryPath);
+    } finally {
+      if (handle) await handle.close().catch(() => undefined);
+      await plugins.fs.rm(temporaryPath, { force: true });
+    }
+  }
+
+  private async withSessionLock<TValue>(
+    sessionId: string,
+    operation: () => Promise<TValue>,
+  ): Promise<TValue> {
+    const lockPath = plugins.path.join(this.rootDir, 'locks', `${this.sessionKey(sessionId)}.lock`);
+    const ownerPath = plugins.path.join(lockPath, 'owner');
+    const ownerToken = plugins.crypto.randomUUID();
+    const ownerRecord = JSON.stringify({ token: ownerToken });
+    await plugins.fs.mkdir(plugins.path.dirname(lockPath), { recursive: true });
+    const startedAt = Date.now();
+    while (true) {
+      try {
+        await plugins.fs.mkdir(lockPath);
+        try {
+          await plugins.fs.writeFile(ownerPath, ownerRecord, 'utf8');
+        } catch (error) {
+          await plugins.fs.rm(lockPath, { recursive: true, force: true });
+          throw error;
+        }
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        if (Date.now() - startedAt >= this.lockTimeoutMs) {
+          throw new Error(
+            `Timed out waiting for the event-store lock for session "${sessionId}" at "${lockPath}".`,
+          );
+        }
+        await sleep(20);
+      }
+    }
+    try {
+      return await operation();
+    } finally {
+      let stillOwner = false;
+      try {
+        const owner = JSON.parse(await plugins.fs.readFile(ownerPath, 'utf8')) as { token?: unknown };
+        stillOwner = owner.token === ownerToken;
+      } catch {}
+      if (stillOwner) await plugins.fs.rm(lockPath, { recursive: true, force: true });
+    }
+  }
+
+  public async load(sessionId: string): Promise<TAgentEventSnapshot | undefined> {
+    const value = await this.readValue(this.snapshotPath(sessionId));
+    return value === undefined ? undefined : decodeSnapshot(value, sessionId);
+  }
+
+  public async save(
+    sessionId: string,
+    events: readonly TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number> {
+    return this.withSessionLock(sessionId, async () => {
+      const filePath = this.snapshotPath(sessionId);
+      const currentValue = await this.readValue(filePath);
+      const actualRevision = currentValue === undefined
+        ? 0
+        : decodeSnapshot(currentValue, sessionId).revision;
+      if (actualRevision !== expectedRevision) {
+        throw new AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
+      }
+      const revision = expectedRevision + 1;
+      await this.writeAtomic(filePath, createSnapshot(sessionId, revision, events));
+      return revision;
+    });
+  }
+
+  public async archive(archive: IAgentEventArchiveV2): Promise<void> {
+    const nextArchive = clone(archive);
+    await this.withSessionLock(archive.sessionId, async () => {
+      const filePath = this.archivePath(archive.sessionId, archive.archiveId);
+      const currentValue = await this.readValue(filePath);
+      if (currentValue !== undefined) {
+        const current = decodeArchive(currentValue, archive.sessionId, archive.archiveId);
+        const currentIds = current.events.map((event) => event.id).join('\n');
+        const nextIds = nextArchive.events.map((event) => event.id).join('\n');
+        if (currentIds !== nextIds) {
+          throw new Error(`Archive "${archive.archiveId}" already exists with different events.`);
+        }
+        return;
+      }
+      await this.writeAtomic(filePath, nextArchive);
+    });
+  }
+
+  public async loadArchive(
+    sessionId: string,
+    archiveId: string,
+  ): Promise<TAgentEventArchive | undefined> {
+    const value = await this.readValue(this.archivePath(sessionId, archiveId));
+    return value === undefined ? undefined : decodeArchive(value, sessionId, archiveId);
+  }
+}

package/ts_agent/plugins.node.ts

@@ -0,0 +1,10 @@
+// node native
+import { AsyncLocalStorage } from 'node:async_hooks';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import * as v8 from 'node:v8';
+
+export { AsyncLocalStorage, crypto, fs, isDeepStrictEqual, path, v8 };
+

package/ts_agent/plugins.portable.ts

@@ -0,0 +1,5 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
+import { strictCircularDeepEqual } from 'fast-equals';
+
+export { sha256, bytesToHex, utf8ToBytes, strictCircularDeepEqual };

package/ts_agent/plugins.ts

@@ -1,13 +1,3 @@
-// node native
-import { AsyncLocalStorage } from 'node:async_hooks';
-import * as crypto from 'node:crypto';
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { isDeepStrictEqual } from 'node:util';
-import * as v8 from 'node:v8';
-
-export { AsyncLocalStorage, crypto, fs, isDeepStrictEqual, path, v8 };
-
 // ai-sdk core
 import { streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
 

package/ts_agent/readme.md

@@ -1,7 +1,11 @@
 Standalone event-driven agent runtime with generation transactions, context and tool execution contracts.
 
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
 Part of the [FlexHarness toolbox](https://code.foss.global/modelprofile.com/flexharness).
-Install the components your project uses. Provider adapters are registered explicitly;
+The toolbox has four package names: `flexharness`, `flexharness-agent`, `flexharness-models`, and `flexharness-providers`. Install the packages your project uses. Provider adapters are registered explicitly;
 the agent and harness do not install or register vendor SDKs.
 
 ```sh
@@ -11,9 +15,11 @@ pnpm add @modelprofile.com/flexharness-agent
 See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
 for composition examples and the SmartAI/SmartAgent migration map.
 
-## Issue Reporting and Security
+## Portable runner
+
+`@modelprofile.com/flexharness-agent/runner` exports `runAgent` and its option/result types for Node and secure browser contexts. It uses the same generation engine, retries and tool-execution ledger, owns its session internally, and closes it before returning. It does not expose session lifecycle or filesystem storage. Modern Web Crypto, streams and structured cloning are required.
 
-Report issues and security concerns through [community.foss.global](https://community.foss.global).
+Use the root entrypoint for the full Node `AgentSession` API, including externally controlled cancellation and close. Its callback ownership uses Node AsyncLocalStorage. Browser code must import `/runner` directly; the root entrypoint remains Node-only. Provider credentials and transports are supplied by the caller.
 
 ## License and Legal Information
 

package/ts_agent/runner.ts

@@ -0,0 +1,40 @@
+import * as plugins from './plugins.portable.js';
+import { AgentSessionEngine } from './classes.sessionengine.js';
+import { runAgentWithSession } from './runtime.run.js';
+import type { IAgentRuntimePlatform } from './runtime.interfaces.js';
+import type { IAgentSessionOptions, IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
+
+const portablePlatform: IAgentRuntimePlatform = {
+  createClaimToken: () => btoa(String.fromCharCode(...globalThis.crypto.getRandomValues(new Uint8Array(32))))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''),
+  hashClaimToken: (token) => plugins.bytesToHex(plugins.sha256(plugins.utf8ToBytes(token))),
+  equalClaimDigests: (left, right) => {
+    if (left.length !== right.length) return false;
+    let difference = 0;
+    for (let index = 0; index < left.length; index++) {
+      difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return difference === 0;
+  },
+  isDeepEqual: plugins.strictCircularDeepEqual,
+  reportListenerError: (error) => console.warn('FLEXHARNESS_SESSION_LISTENER_ERROR', error),
+};
+
+// This class and its factory are deliberately not exported. Callbacks receive
+// data only; no caller can close this session from inside its active callback.
+class RunnerSession extends AgentSessionEngine {
+  constructor(options: IAgentSessionOptions) {
+    super(options, portablePlatform, { kind: 'encapsulated' });
+  }
+
+  public static create(options: IAgentSessionOptions): Promise<RunnerSession> {
+    return this.createWithFactory(options, () => new RunnerSession(options));
+  }
+}
+
+/** Run in Node or a secure browser context, with internally owned cleanup. */
+export function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult> {
+  return runAgentWithSession(options, (sessionOptions) => RunnerSession.create(sessionOptions));
+}
+
+export type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';

package/ts_agent/runtime.interfaces.ts

@@ -0,0 +1,21 @@
+/** Internal platform boundary; only the documented agent entrypoints are exported. */
+export interface IAgentCallbackState {
+  active: boolean;
+}
+
+export interface IAgentCallbackScope {
+  getStore(): IAgentCallbackState | undefined;
+  run<TValue>(state: IAgentCallbackState, callback: () => TValue): TValue;
+}
+
+export type TAgentSessionOwnership =
+  | { kind: 'exposed'; callbackScope: IAgentCallbackScope }
+  | { kind: 'encapsulated' };
+
+export interface IAgentRuntimePlatform {
+  createClaimToken(): string;
+  hashClaimToken(token: string): string;
+  equalClaimDigests(left: string, right: string): boolean;
+  isDeepEqual(left: unknown, right: unknown): boolean;
+  reportListenerError(error: unknown): void;
+}

package/ts_agent/runtime.run.ts

@@ -0,0 +1,107 @@
+import type { IAgentSession, IAgentSessionOptions } from './smartagent.interfaces.js';
+import type {
+  IAgentRunOptions,
+  IAgentRunResult,
+  IAgentToolCallRecord,
+} from './smartagent.interfaces.js';
+
+const mergeToolCalls = (
+  target: IAgentToolCallRecord[],
+  source: readonly IAgentToolCallRecord[],
+): void => {
+  const indexes = new Map(target.map((record, index) => [record.toolCallId, index]));
+  for (const record of source) {
+    const existingIndex = indexes.get(record.toolCallId);
+    if (existingIndex === undefined) {
+      target.push({ ...record });
+      indexes.set(record.toolCallId, target.length - 1);
+    } else {
+      target[existingIndex] = { ...target[existingIndex], ...record };
+    }
+  }
+};
+
+export async function runAgentWithSession(
+  options: IAgentRunOptions,
+  createSession: (options: IAgentSessionOptions) => Promise<IAgentSession>,
+): Promise<IAgentRunResult> {
+  const session = await createSession({
+    model: options.model,
+    system: options.system,
+    tools: options.tools,
+    providerOptions: options.providerOptions,
+    sessionId: options.sessionId,
+    eventStore: options.eventStore,
+    cache: options.cache,
+    maxSteps: options.maxSteps,
+    messages: options.messages,
+    events: options.events,
+    executionContext: options.executionContext,
+    contextBuilder: options.contextBuilder,
+    contextCompactor: options.contextCompactor,
+    eventRetention: options.eventRetention,
+    changeListenerTimeoutMs: options.changeListenerTimeoutMs,
+    maxPendingSessionChanges: options.maxPendingSessionChanges,
+    generationLeaseCleanupTimeoutMs: options.generationLeaseCleanupTimeoutMs,
+    maxArchivedTransactionTombstones: options.maxArchivedTransactionTombstones,
+    onToken: options.onToken,
+    onReasoningStart: options.onReasoningStart,
+    onReasoningDelta: options.onReasoningDelta,
+    onReasoningEnd: options.onReasoningEnd,
+    onToolCallStart: options.onToolCallStart,
+    onToolCallUpdate: options.onToolCallUpdate,
+    onToolCallFinish: options.onToolCallFinish,
+    onToolCall: options.onToolCall,
+    onToolResult: options.onToolResult,
+    onContextOverflow: options.onContextOverflow,
+    maxContextOverflowRetries: options.maxContextOverflowRetries,
+  });
+  let totalSteps = 0;
+  let totalInput = 0;
+  let totalOutput = 0;
+  let totalCacheRead = 0;
+  let totalCacheWrite = 0;
+  let validationRetries = 0;
+  const toolCalls: IAgentToolCallRecord[] = [];
+
+  try {
+    await session.pushUserMessage(options.prompt);
+    while (true) {
+      const generationResult = await session.generate({
+        maxSteps: options.maxSteps,
+        abort: options.abort,
+      });
+      totalSteps += generationResult.steps;
+      totalInput += generationResult.usage.inputTokens;
+      totalOutput += generationResult.usage.outputTokens;
+      totalCacheRead += generationResult.usage.cacheReadTokens;
+      totalCacheWrite += generationResult.usage.cacheWriteTokens;
+      mergeToolCalls(toolCalls, generationResult.toolCalls);
+
+      const runResult: IAgentRunResult = {
+        text: generationResult.text,
+        messages: session.getModelMessages(),
+        steps: totalSteps,
+        finishReason: generationResult.finishReason,
+        usage: {
+          inputTokens: totalInput,
+          outputTokens: totalOutput,
+          totalTokens: totalInput + totalOutput,
+          cacheReadTokens: totalCacheRead,
+          cacheWriteTokens: totalCacheWrite,
+        },
+        toolCalls,
+      };
+
+      const validationPrompt = await options.validateCompletion?.(runResult);
+      if (typeof validationPrompt !== 'string') return runResult;
+      if (validationRetries >= (options.maxValidationRetries ?? 0)) {
+        throw new Error(`Agent completion validation failed: ${validationPrompt}`);
+      }
+      validationRetries++;
+      await session.pushUserMessage(validationPrompt);
+    }
+  } finally {
+    await session.close();
+  }
+}

package/ts_agent/smartagent.classes.agent.ts

@@ -1,104 +1,7 @@
 import { AgentSession } from './smartagent.classes.session.js';
-import type {
-  IAgentRunOptions,
-  IAgentRunResult,
-  IAgentToolCallRecord,
-} from './smartagent.interfaces.js';
+import { runAgentWithSession } from './runtime.run.js';
+import type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
 
-const mergeToolCalls = (
-  target: IAgentToolCallRecord[],
-  source: readonly IAgentToolCallRecord[],
-): void => {
-  const indexes = new Map(target.map((record, index) => [record.toolCallId, index]));
-  for (const record of source) {
-    const existingIndex = indexes.get(record.toolCallId);
-    if (existingIndex === undefined) {
-      target.push({ ...record });
-      indexes.set(record.toolCallId, target.length - 1);
-    } else {
-      target[existingIndex] = { ...target[existingIndex], ...record };
-    }
-  }
-};
-
-export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult> {
-  const session = await AgentSession.create({
-    model: options.model,
-    system: options.system,
-    tools: options.tools,
-    providerOptions: options.providerOptions,
-    sessionId: options.sessionId,
-    eventStore: options.eventStore,
-    cache: options.cache,
-    maxSteps: options.maxSteps,
-    messages: options.messages,
-    events: options.events,
-    executionContext: options.executionContext,
-    contextBuilder: options.contextBuilder,
-    contextCompactor: options.contextCompactor,
-    eventRetention: options.eventRetention,
-    changeListenerTimeoutMs: options.changeListenerTimeoutMs,
-    maxPendingSessionChanges: options.maxPendingSessionChanges,
-    generationLeaseCleanupTimeoutMs: options.generationLeaseCleanupTimeoutMs,
-    maxArchivedTransactionTombstones: options.maxArchivedTransactionTombstones,
-    onToken: options.onToken,
-    onReasoningStart: options.onReasoningStart,
-    onReasoningDelta: options.onReasoningDelta,
-    onReasoningEnd: options.onReasoningEnd,
-    onToolCallStart: options.onToolCallStart,
-    onToolCallUpdate: options.onToolCallUpdate,
-    onToolCallFinish: options.onToolCallFinish,
-    onToolCall: options.onToolCall,
-    onToolResult: options.onToolResult,
-    onContextOverflow: options.onContextOverflow,
-    maxContextOverflowRetries: options.maxContextOverflowRetries,
-  });
-  let totalSteps = 0;
-  let totalInput = 0;
-  let totalOutput = 0;
-  let totalCacheRead = 0;
-  let totalCacheWrite = 0;
-  let validationRetries = 0;
-  const toolCalls: IAgentToolCallRecord[] = [];
-
-  try {
-    await session.pushUserMessage(options.prompt);
-    while (true) {
-      const generationResult = await session.generate({
-        maxSteps: options.maxSteps,
-        abort: options.abort,
-      });
-      totalSteps += generationResult.steps;
-      totalInput += generationResult.usage.inputTokens;
-      totalOutput += generationResult.usage.outputTokens;
-      totalCacheRead += generationResult.usage.cacheReadTokens;
-      totalCacheWrite += generationResult.usage.cacheWriteTokens;
-      mergeToolCalls(toolCalls, generationResult.toolCalls);
-
-      const runResult: IAgentRunResult = {
-        text: generationResult.text,
-        messages: session.getModelMessages(),
-        steps: totalSteps,
-        finishReason: generationResult.finishReason,
-        usage: {
-          inputTokens: totalInput,
-          outputTokens: totalOutput,
-          totalTokens: totalInput + totalOutput,
-          cacheReadTokens: totalCacheRead,
-          cacheWriteTokens: totalCacheWrite,
-        },
-        toolCalls,
-      };
-
-      const validationPrompt = await options.validateCompletion?.(runResult);
-      if (typeof validationPrompt !== 'string') return runResult;
-      if (validationRetries >= (options.maxValidationRetries ?? 0)) {
-        throw new Error(`Agent completion validation failed: ${validationPrompt}`);
-      }
-      validationRetries++;
-      await session.pushUserMessage(validationPrompt);
-    }
-  } finally {
-    await session.close();
-  }
+export function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult> {
+  return runAgentWithSession(options, (sessionOptions) => AgentSession.create(sessionOptions));
 }