@autobe/agent 0.30.0-dev.20260315 → 0.30.1

package/src/utils/TimedConversation.ts

@@ -1,125 +1,125 @@
-import { MicroAgentica, MicroAgenticaHistory } from "@agentica/core";
-import { ConditionVariable, IPointer, Singleton, sleep_for } from "tstl";
-
-import { AutoBeTimeoutError } from "./AutoBeTimeoutError";
-
-/**
- * Wraps LLM conversation with timeout enforcement and discriminated result
- * types.
- *
- * Prevents hanging indefinitely when LLM APIs become unresponsive or requests
- * take excessively long. Uses AbortController to cancel in-flight requests when
- * timeout expires. Returns discriminated union enabling callers to handle
- * success/timeout/error cases separately.
- *
- * @author Samchon
- */
-export namespace TimedConversation {
-  /** Configuration for timed conversation execution. */
-  export interface IProps {
-    /** MicroAgentica agent to execute conversation */
-    agent: MicroAgentica;
-    /** User message to send */
-    message: string;
-    /** Timeout in milliseconds, or null for no timeout */
-    timeout: number | null;
-  }
-
-  /** Discriminated union of possible conversation outcomes. */
-  export type IResult = ISuccessResult | ITimeoutResult | IErrorResult;
-
-  /** Successful conversation completion. */
-  export interface ISuccessResult {
-    type: "success";
-    histories: MicroAgenticaHistory[];
-  }
-
-  /** Conversation exceeded timeout limit. */
-  export interface ITimeoutResult {
-    type: "timeout";
-    error: AutoBeTimeoutError;
-  }
-
-  /** Conversation failed with error other than timeout. */
-  export interface IErrorResult {
-    type: "error";
-    error: Error;
-  }
-
-  /**
-   * Executes conversation with optional timeout enforcement.
-   *
-   * If timeout is null, executes without time limit. Otherwise, sets up timeout
-   * handler that aborts the request and returns timeout result. Uses condition
-   * variable for synchronization between conversation and timeout threads.
-   *
-   * @param props Agent, message, and timeout configuration
-   * @returns Discriminated result indicating success, timeout, or error
-   */
-  export const process = async (props: IProps): Promise<IResult> => {
-    if (props.timeout === null)
-      try {
-        const histories: MicroAgenticaHistory[] = await props.agent.conversate(
-          props.message,
-        );
-        return {
-          type: "success",
-          histories,
-        };
-      } catch (error) {
-        return {
-          type: "error",
-          error: error as Error,
-        };
-      }
-
-    // PREPARE TIMEOUT HANDLERS
-    const result: IPointer<IResult | null> = {
-      value: null,
-    };
-    const holder: ConditionVariable = new ConditionVariable();
-    const abort: AbortController = new AbortController();
-    const timeout: Singleton<NodeJS.Timeout> = new Singleton(() =>
-      setTimeout(() => {
-        if (result.value !== null) return;
-        result.value = {
-          type: "timeout",
-          error: new AutoBeTimeoutError(`Timeout, over ${props.timeout} ms.`),
-        };
-        abort.abort(`Timeout, over ${props.timeout} ms`);
-        void holder.notify_all().catch(() => {});
-      }, props.timeout!),
-    );
-
-    // DO CONVERSATE
-    props.agent.on("request", () => {
-      timeout.get();
-    });
-    props.agent
-      .conversate(props.message, {
-        abortSignal: abort.signal,
-      })
-      .then(
-        (v) =>
-          (result.value ??= {
-            type: "success",
-            histories: v,
-          }),
-      )
-      .catch(
-        (e) =>
-          (result.value ??= {
-            type: "error",
-            error: e as Error,
-          }),
-      )
-      .finally(() => {
-        void holder.notify_all().catch(() => {});
-        clearTimeout(timeout.get());
-      });
-
-    await holder.wait();
-    await sleep_for(0);
-    return result.value!;
-  };
-}
+import { MicroAgentica, MicroAgenticaHistory } from "@agentica/core";
+import { ConditionVariable, IPointer, Singleton, sleep_for } from "tstl";
+
+import { AutoBeTimeoutError } from "./AutoBeTimeoutError";
+
+/**
+ * Wraps LLM conversation with timeout enforcement and discriminated result
+ * types.
+ *
+ * Prevents hanging indefinitely when LLM APIs become unresponsive or requests
+ * take excessively long. Uses AbortController to cancel in-flight requests when
+ * timeout expires. Returns discriminated union enabling callers to handle
+ * success/timeout/error cases separately.
+ *
+ * @author Samchon
+ */
+export namespace TimedConversation {
+  /** Configuration for timed conversation execution. */
+  export interface IProps {
+    /** MicroAgentica agent to execute conversation */
+    agent: MicroAgentica;
+    /** User message to send */
+    message: string;
+    /** Timeout in milliseconds, or null for no timeout */
+    timeout: number | null;
+  }
+
+  /** Discriminated union of possible conversation outcomes. */
+  export type IResult = ISuccessResult | ITimeoutResult | IErrorResult;
+
+  /** Successful conversation completion. */
+  export interface ISuccessResult {
+    type: "success";
+    histories: MicroAgenticaHistory[];
+  }
+
+  /** Conversation exceeded timeout limit. */
+  export interface ITimeoutResult {
+    type: "timeout";
+    error: AutoBeTimeoutError;
+  }
+
+  /** Conversation failed with error other than timeout. */
+  export interface IErrorResult {
+    type: "error";
+    error: Error;
+  }
+
+  /**
+   * Executes conversation with optional timeout enforcement.
+   *
+   * If timeout is null, executes without time limit. Otherwise, sets up timeout
+   * handler that aborts the request and returns timeout result. Uses condition
+   * variable for synchronization between conversation and timeout threads.
+   *
+   * @param props Agent, message, and timeout configuration
+   * @returns Discriminated result indicating success, timeout, or error
+   */
+  export const process = async (props: IProps): Promise<IResult> => {
+    if (props.timeout === null)
+      try {
+        const histories: MicroAgenticaHistory[] = await props.agent.conversate(
+          props.message,
+        );
+        return {
+          type: "success",
+          histories,
+        };
+      } catch (error) {
+        return {
+          type: "error",
+          error: error as Error,
+        };
+      }
+
+    // PREPARE TIMEOUT HANDLERS
+    const result: IPointer<IResult | null> = {
+      value: null,
+    };
+    const holder: ConditionVariable = new ConditionVariable();
+    const abort: AbortController = new AbortController();
+    const timeout: Singleton<NodeJS.Timeout> = new Singleton(() =>
+      setTimeout(() => {
+        if (result.value !== null) return;
+        result.value = {
+          type: "timeout",
+          error: new AutoBeTimeoutError(`Timeout, over ${props.timeout} ms.`),
+        };
+        abort.abort(`Timeout, over ${props.timeout} ms`);
+        void holder.notify_all().catch(() => {});
+      }, props.timeout!),
+    );
+
+    // DO CONVERSATE
+    props.agent.on("request", () => {
+      timeout.get();
+    });
+    props.agent
+      .conversate(props.message, {
+        abortSignal: abort.signal,
+      })
+      .then(
+        (v) =>
+          (result.value ??= {
+            type: "success",
+            histories: v,
+          }),
+      )
+      .catch(
+        (e) =>
+          (result.value ??= {
+            type: "error",
+            error: e as Error,
+          }),
+      )
+      .finally(() => {
+        void holder.notify_all().catch(() => {});
+        clearTimeout(timeout.get());
+      });
+
+    await holder.wait();
+    await sleep_for(0);
+    return result.value!;
+  };
+}

package/src/utils/backoffRetry.ts

@@ -1,169 +1,169 @@
-/** Configuration options for exponential backoff retry behavior. */
-export interface RetryOptions {
-  /** Maximum number of retry attempts (default: 5) */
-  maxRetries: number;
-  /** Base delay in milliseconds (default: 4000) */
-  baseDelay: number;
-  /** Maximum delay in milliseconds (default: 60000) */
-  maxDelay: number;
-  /** Jitter factor for randomization (0-1, default: 0.8) */
-  jitter: number;
-  /** Function to determine if error should trigger retry (default: isRetryError) */
-  handleError: (error: unknown) => boolean;
-}
-
-/**
- * Retries failed LLM API calls with exponential backoff and jitter.
- *
- * Automatically retries transient failures (rate limits, server errors, network
- * issues) while immediately failing on permanent errors (quota exceeded,
- * invalid requests). Uses exponential backoff with randomized jitter to avoid
- * thundering herd problems when multiple concurrent requests fail
- * simultaneously.
- *
- * The retry logic is critical for production reliability: LLM APIs frequently
- * return temporary 429/5xx errors under heavy load, and network timeouts are
- * common. Without retry, these transient failures would cascade into
- * user-visible errors despite being automatically recoverable.
- *
- * @author Kakasoo
- * @param fn Async function to execute with retry logic
- * @param options Retry configuration (maxRetries, delays, error handler)
- * @returns Promise resolving to function result if successful
- * @throws Last encountered error if all retry attempts exhausted
- */
-export async function randomBackoffRetry<T>(
-  fn: () => Promise<T>,
-  options: Partial<RetryOptions> = {},
-): Promise<T> {
-  const {
-    maxRetries = 5,
-    baseDelay = 4_000,
-    maxDelay = 60_000,
-    jitter = 0.8,
-    handleError = isRetryError,
-  } = options;
-
-  let lastError: unknown;
-
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (err) {
-      lastError = err;
-
-      if (attempt === maxRetries - 1) throw err;
-
-      if (!handleError(err)) throw err;
-
-      const tempDelay = Math.min(baseDelay * 2 ** attempt, maxDelay);
-      const delay = tempDelay * (1 + Math.random() * jitter);
-
-      await new Promise((res) => setTimeout(res, delay));
-    }
-  }
-
-  throw lastError;
-}
-
-/**
- * Calculates retry delay using exponential backoff with jitter.
- *
- * Throws immediately for non-retryable errors or when retry count exceeds 5.
- * Used by orchestrators that need explicit delay calculation without automatic
- * retry loop execution.
- *
- * @param props Retry count and error to evaluate
- * @returns Calculated delay in milliseconds
- * @throws Original error if non-retryable or max retries exceeded
- */
-export function randomBackoffStrategy(props: {
-  count: number;
-  error: unknown;
-}): number {
-  const { count, error } = props;
-  if (count > 5) {
-    throw error;
-  }
-
-  if (isRetryError(error) === false) {
-    throw error;
-  }
-
-  const baseDelay = 4_000;
-  const maxDelay = 60_000;
-  const jitter = 0.8;
-  const tempDelay = Math.min(baseDelay * 2 ** count, maxDelay);
-  const delay = tempDelay * (1 + Math.random() * jitter);
-
-  return delay;
-}
-
-/**
- * Determines if an error represents a transient failure that should trigger
- * retry.
- *
- * Returns `true` for retryable errors (rate limits, server errors, network
- * issues) and `false` for permanent failures (quota exceeded, invalid
- * requests). This classification prevents wasting resources retrying
- * unrecoverable errors.
- *
- * @param error Error object from LLM API or network layer
- * @returns `true` if error is retryable, `false` otherwise
- */
-function isRetryError(
-  // biome-ignore lint: @todo SunRabbit
-  error: any,
-): boolean {
-  // 1) Quota exceeded → No retry
-  if (
-    error?.code === "insufficient_quota" ||
-    error?.error?.type === "insufficient_quota"
-  ) {
-    return false;
-  }
-
-  // 2) 5xx / server_error → Retry
-  //    Streaming errors from OpenRouter may have status: undefined but code: 502
-  if (
-    (typeof error?.status === "number" && error.status >= 500) ||
-    (typeof error?.code === "number" && error.code >= 500) ||
-    error?.error?.type === "server_error"
-  ) {
-    return true;
-  }
-
-  // 3) HTTP 429
-  if (error?.status === 429) {
-    return true;
-  }
-
-  // 4) undici / network related
-  const code = error?.code || error?.cause?.code;
-  if (
-    [
-      "UND_ERR_SOCKET",
-      "UND_ERR_CONNECT_TIMEOUT",
-      "ETIMEDOUT",
-      "ECONNRESET",
-      "EPIPE",
-    ].includes(code)
-  ) {
-    return true;
-  }
-
-  // 5) fetch abort
-  if (error?.message === "terminated" || error?.name === "AbortError") {
-    return true;
-  }
-
-  if (
-    (error?.message as string)?.startsWith(
-      `SyntaxError: Expected ',' or '}' after property value in JSON at position`,
-    )
-  ) {
-    return true;
-  }
-
-  return false;
-}
+/** Configuration options for exponential backoff retry behavior. */
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 5) */
+  maxRetries: number;
+  /** Base delay in milliseconds (default: 4000) */
+  baseDelay: number;
+  /** Maximum delay in milliseconds (default: 60000) */
+  maxDelay: number;
+  /** Jitter factor for randomization (0-1, default: 0.8) */
+  jitter: number;
+  /** Function to determine if error should trigger retry (default: isRetryError) */
+  handleError: (error: unknown) => boolean;
+}
+
+/**
+ * Retries failed LLM API calls with exponential backoff and jitter.
+ *
+ * Automatically retries transient failures (rate limits, server errors, network
+ * issues) while immediately failing on permanent errors (quota exceeded,
+ * invalid requests). Uses exponential backoff with randomized jitter to avoid
+ * thundering herd problems when multiple concurrent requests fail
+ * simultaneously.
+ *
+ * The retry logic is critical for production reliability: LLM APIs frequently
+ * return temporary 429/5xx errors under heavy load, and network timeouts are
+ * common. Without retry, these transient failures would cascade into
+ * user-visible errors despite being automatically recoverable.
+ *
+ * @author Kakasoo
+ * @param fn Async function to execute with retry logic
+ * @param options Retry configuration (maxRetries, delays, error handler)
+ * @returns Promise resolving to function result if successful
+ * @throws Last encountered error if all retry attempts exhausted
+ */
+export async function randomBackoffRetry<T>(
+  fn: () => Promise<T>,
+  options: Partial<RetryOptions> = {},
+): Promise<T> {
+  const {
+    maxRetries = 5,
+    baseDelay = 4_000,
+    maxDelay = 60_000,
+    jitter = 0.8,
+    handleError = isRetryError,
+  } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      if (attempt === maxRetries - 1) throw err;
+
+      if (!handleError(err)) throw err;
+
+      const tempDelay = Math.min(baseDelay * 2 ** attempt, maxDelay);
+      const delay = tempDelay * (1 + Math.random() * jitter);
+
+      await new Promise((res) => setTimeout(res, delay));
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Calculates retry delay using exponential backoff with jitter.
+ *
+ * Throws immediately for non-retryable errors or when retry count exceeds 5.
+ * Used by orchestrators that need explicit delay calculation without automatic
+ * retry loop execution.
+ *
+ * @param props Retry count and error to evaluate
+ * @returns Calculated delay in milliseconds
+ * @throws Original error if non-retryable or max retries exceeded
+ */
+export function randomBackoffStrategy(props: {
+  count: number;
+  error: unknown;
+}): number {
+  const { count, error } = props;
+  if (count > 5) {
+    throw error;
+  }
+
+  if (isRetryError(error) === false) {
+    throw error;
+  }
+
+  const baseDelay = 4_000;
+  const maxDelay = 60_000;
+  const jitter = 0.8;
+  const tempDelay = Math.min(baseDelay * 2 ** count, maxDelay);
+  const delay = tempDelay * (1 + Math.random() * jitter);
+
+  return delay;
+}
+
+/**
+ * Determines if an error represents a transient failure that should trigger
+ * retry.
+ *
+ * Returns `true` for retryable errors (rate limits, server errors, network
+ * issues) and `false` for permanent failures (quota exceeded, invalid
+ * requests). This classification prevents wasting resources retrying
+ * unrecoverable errors.
+ *
+ * @param error Error object from LLM API or network layer
+ * @returns `true` if error is retryable, `false` otherwise
+ */
+function isRetryError(
+  // biome-ignore lint: @todo SunRabbit
+  error: any,
+): boolean {
+  // 1) Quota exceeded → No retry
+  if (
+    error?.code === "insufficient_quota" ||
+    error?.error?.type === "insufficient_quota"
+  ) {
+    return false;
+  }
+
+  // 2) 5xx / server_error → Retry
+  //    Streaming errors from OpenRouter may have status: undefined but code: 502
+  if (
+    (typeof error?.status === "number" && error.status >= 500) ||
+    (typeof error?.code === "number" && error.code >= 500) ||
+    error?.error?.type === "server_error"
+  ) {
+    return true;
+  }
+
+  // 3) HTTP 429
+  if (error?.status === 429) {
+    return true;
+  }
+
+  // 4) undici / network related
+  const code = error?.code || error?.cause?.code;
+  if (
+    [
+      "UND_ERR_SOCKET",
+      "UND_ERR_CONNECT_TIMEOUT",
+      "ETIMEDOUT",
+      "ECONNRESET",
+      "EPIPE",
+    ].includes(code)
+  ) {
+    return true;
+  }
+
+  // 5) fetch abort
+  if (error?.message === "terminated" || error?.name === "AbortError") {
+    return true;
+  }
+
+  if (
+    (error?.message as string)?.startsWith(
+      `SyntaxError: Expected ',' or '}' after property value in JSON at position`,
+    )
+  ) {
+    return true;
+  }
+
+  return false;
+}

package/src/utils/divideArray.ts

@@ -1,35 +1,35 @@
-/**
- * Divides an array into chunks of at most `capacity` elements each for parallel
- * batch processing.
- *
- * Used with `executeCachedBatch` to split large task lists into smaller batches
- * that can be processed concurrently. The `capacity` parameter controls the
- * maximum number of elements per chunk, not the number of chunks. This enables
- * balancing parallelism against prompt cache efficiency.
- *
- * For example, dividing 100 operations with capacity=3 creates 34 chunks of 3
- * operations each (the last chunk may have fewer elements if the array length
- * is not a multiple of capacity). This allows processing 100 operations in 34
- * parallel batches of up to 3 operations each.
- *
- * @param props Object containing the array to divide and the maximum chunk size
- *   (`capacity`)
- * @returns Array of chunks with at most `capacity` elements each
- * @throws Error if capacity is non-positive, NaN, or Infinity
- */
-export function divideArray<T>(props: { array: T[]; capacity: number }): T[][] {
-  if (props.capacity <= 0) {
-    throw new Error("Capacity must be a positive integer");
-  }
-  if (Number.isNaN(props.capacity)) {
-    throw new TypeError("Capacity must be a positive integer");
-  }
-  if (props.capacity === Infinity) {
-    throw new Error("Capacity must be a positive integer");
-  }
-
-  const size: number = Math.ceil(props.array.length / props.capacity);
-  const capacity: number = Math.ceil(props.array.length / size);
-  const replica: T[] = props.array.slice();
-  return Array.from({ length: size }, () => replica.splice(0, capacity));
-}
+/**
+ * Divides an array into chunks of at most `capacity` elements each for parallel
+ * batch processing.
+ *
+ * Used with `executeCachedBatch` to split large task lists into smaller batches
+ * that can be processed concurrently. The `capacity` parameter controls the
+ * maximum number of elements per chunk, not the number of chunks. This enables
+ * balancing parallelism against prompt cache efficiency.
+ *
+ * For example, dividing 100 operations with capacity=3 creates 34 chunks of 3
+ * operations each (the last chunk may have fewer elements if the array length
+ * is not a multiple of capacity). This allows processing 100 operations in 34
+ * parallel batches of up to 3 operations each.
+ *
+ * @param props Object containing the array to divide and the maximum chunk size
+ *   (`capacity`)
+ * @returns Array of chunks with at most `capacity` elements each
+ * @throws Error if capacity is non-positive, NaN, or Infinity
+ */
+export function divideArray<T>(props: { array: T[]; capacity: number }): T[][] {
+  if (props.capacity <= 0) {
+    throw new Error("Capacity must be a positive integer");
+  }
+  if (Number.isNaN(props.capacity)) {
+    throw new TypeError("Capacity must be a positive integer");
+  }
+  if (props.capacity === Infinity) {
+    throw new Error("Capacity must be a positive integer");
+  }
+
+  const size: number = Math.ceil(props.array.length / props.capacity);
+  const capacity: number = Math.ceil(props.array.length / size);
+  const replica: T[] = props.array.slice();
+  return Array.from({ length: size }, () => replica.splice(0, capacity));
+}