@autobe/agent 0.8.0 → 0.9.0

package/src/orchestrate/test/transformTestScenarioHistories.ts

@@ -1,5 +1,4 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
-import { AutoBeOpenApi } from "@autobe/interface";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptConstant";
@@ -7,8 +6,6 @@ import { AutoBeState } from "../../context/AutoBeState";
 
 export const transformTestScenarioHistories = (
   state: AutoBeState,
-  allEndpoints: AutoBeOpenApi.IEndpoint[],
-  files: Record<string, string>,
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
@@ -87,47 +84,6 @@ export const transformTestScenarioHistories = (
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.TEST,
     },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "# Result of Analyze Agent",
-        "- The following document contains the user requirements that were extracted through conversations with the user by the Analyze Agent.",
-        "- The database schema was designed based on these requirements, so you may refer to this document when writing test code or reviewing the schema.",
-        "",
-        `## User Request`,
-        "",
-        `- ${state.analyze.reason}`,
-        "",
-        `## Requirement Analysis Report`,
-        "",
-        "```json",
-        JSON.stringify(state.analyze.files),
-        "```",
-      ].join("\n"),
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "# Result of Prisma Agent",
-        "- Given the following database schema and entity-relationship diagram, write appropriate test code to validate the constraints and relationships defined in the schema. For example, if there is a unique column, include a test that ensures its uniqueness.",
-        "- The test code should strictly adhere to the schema and relationships—no violations of constraints should occur.",
-        "- Use the information from the schema and diagram to design meaningful and accurate test cases.",
-        "",
-        "## Prisma DB Schema",
-        "```json",
-        JSON.stringify(state.prisma.schemas),
-        "```",
-        "",
-        "## Entity Relationship Diagrams",
-        "```json",
-        JSON.stringify(state.prisma.compiled.diagrams),
-        "```",
-      ].join("\n"),
-    },
     {
       id: v4(),
       created_at: new Date().toISOString(),
@@ -145,40 +101,5 @@ export const transformTestScenarioHistories = (
         "```",
       ].join("\n"),
     },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        `This is a description of different APIs.`,
-        `Different APIs may have to be called to create one.`,
-        `Check which functions have been developed.`,
-        "```json",
-        JSON.stringify(allEndpoints, null, 2),
-        "```",
-      ].join("\n"),
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "Below is basically the generated test code,",
-        "which is a test to verify that the API is simply called and successful.",
-        "Since there is already an automatically generated API,",
-        "when a user requests to create a test scenario, two or more APIs must be combined,",
-        "but a test in which the currently given endpoint is the main must be created.",
-        '"Input Test Files" should be selected from the list of files here.',
-        "```json",
-        JSON.stringify(files, null, 2),
-        "```",
-      ].join("\n"),
-    },
   ];
 };

package/src/structures/IAutoBeConfig.ts

@@ -1,25 +1,63 @@
+/**
+ * Interface defining behavioral configuration for AutoBeAgent localization and
+ * context.
+ *
+ * This interface customizes the agent's communication style, language
+ * preferences, and geographical context to provide personalized vibe coding
+ * experiences. The configuration enables culturally appropriate interactions
+ * and regionally aware development decisions throughout the automated
+ * development pipeline.
+ *
+ * Locale and timezone settings influence not only the language of communication
+ * but also contextual understanding of regulatory requirements, business
+ * practices, and temporal considerations that may affect requirements analysis,
+ * database design, API specifications, and implementation approaches.
+ *
+ * @author Samchon
+ */
 export interface IAutoBeConfig {
   /**
-   * Locale of the A.I. chatbot.
+   * Language and cultural locale preference for AI agent communication.
    *
-   * If you configure this property, the A.I. chatbot will conversate with the
-   * given locale. You can get the locale value by
+   * Configures the language and cultural context for all AI assistant responses
+   * throughout the vibe coding process. When specified, the agent will
+   * communicate in the preferred language while respecting cultural conventions
+   * and linguistic nuances during requirements gathering, progress updates, and
+   * guidance provision.
+   *
+   * The locale setting also influences the agent's understanding of regional
+   * business practices, regulatory considerations, and cultural expectations
+   * that may impact software design decisions and implementation approaches.
+   *
+   * Common formats follow BCP 47 language tags such as "en-US", "ko-KR",
+   * "ja-JP", "zh-CN", "de-DE", etc. Platform-specific detection methods:
    *
    * - Browser: `navigator.language`
-   * - NodeJS: `process.env.LANG.split(".")[0]`
+   * - Node.js: `process.env.LANG.split(".")[0]`
    *
-   * @default your_locale
+   * @default System locale or "en" if unavailable
    */
   locale?: string;
 
   /**
-   * Timezone of the A.I. chatbot.
+   * Geographic timezone for temporal context and time-sensitive operations.
+   *
+   * Provides timezone awareness for proper handling of time-related
+   * considerations during the vibe coding process. This includes scheduling
+   * references, temporal business logic requirements, timestamp handling in
+   * generated code, and time-based communications that need to be
+   * contextualized for the user's local time.
+   *
+   * Timezone awareness ensures that generated applications properly handle time
+   * zones, that scheduling-related requirements are interpreted correctly, and
+   * that temporal references in documentation and code comments reflect the
+   * user's geographical context.
    *
-   * If you configure this property, the A.I. chatbot will consider the given
-   * timezone. You can get the timezone value by
-   * `Intl.DateTimeFormat().resolvedOptions().timeZone`.
+   * Format follows IANA Time Zone Database identifiers such as
+   * "America/New_York", "Asia/Seoul", "Europe/London", "Pacific/Auckland", etc.
+   * Platform detection: `Intl.DateTimeFormat().resolvedOptions().timeZone`
    *
-   * @default your_timezone
+   * @default System timezone or "UTC" if unavailable
    */
   timezone?: string;
 }

package/src/structures/IAutoBeProps.ts

@@ -4,10 +4,101 @@ import { ILlmSchema } from "@samchon/openapi";
 import { IAutoBeConfig } from "./IAutoBeConfig";
 import { IAutoBeVendor } from "./IAutoBeVendor";
 
+/**
+ * Configuration properties for initializing an AutoBeAgent instance.
+ *
+ * This interface defines all the essential parameters required to create and
+ * configure an AutoBeAgent for vibe coding operations. The properties establish
+ * the AI model capabilities, vendor connectivity, compilation infrastructure,
+ * behavioral context, and optional session continuity through conversation
+ * histories.
+ *
+ * The configuration enables type-safe AI function calling through
+ * model-specific schema generation, ensures compatibility with various AI
+ * service providers, and provides the compilation tools necessary for the
+ * sophisticated AST-based development pipeline that transforms conversations
+ * into working software.
+ *
+ * @author Samchon
+ */
 export interface IAutoBeProps<Model extends ILlmSchema.Model> {
+  /**
+   * AI model type specification for type-safe function calling schema
+   * generation.
+   *
+   * Determines the specific AI model schema used for generating function
+   * calling interfaces through
+   * [`typia.llm.application()`](https://typia.io/docs/llm/application). This
+   * type parameter ensures compile-time type safety and enables model-specific
+   * optimizations in the AI function calling interface generation process.
+   *
+   * Common values include "chatgpt" for OpenAI models, "claude" for Anthropic
+   * models, "deepseek" for DeepSeek models, and "llama" for Meta Llama models.
+   * The choice affects function calling capabilities, parameter limitations,
+   * and schema requirements throughout the vibe coding pipeline.
+   *
+   * Note that Google Gemini ("gemini") is not supported due to its lack of
+   * reference types and union types support required for OpenAPI document
+   * composition in the vibe coding process.
+   */
   model: Model;
+
+  /**
+   * AI vendor configuration for service provider integration.
+   *
+   * Defines the complete AI service connection including the OpenAI SDK
+   * instance, model identifier, request options, and concurrency controls. This
+   * configuration enables the AutoBeAgent to connect with various AI providers
+   * while maintaining consistent functionality across the entire automated
+   * development workflow.
+   *
+   * The vendor settings determine the AI capabilities available for
+   * requirements analysis, database design, API specification, testing, and
+   * implementation phases of the vibe coding process.
+   */
   vendor: IAutoBeVendor;
+
+  /**
+   * Compilation infrastructure for TypeScript, Prisma, and OpenAPI operations.
+   *
+   * Provides the essential compilation tools required for the sophisticated
+   * AST-based development pipeline. The compiler handles validation,
+   * transformation, and code generation across all development phases including
+   * Prisma schema compilation, OpenAPI document validation, and TypeScript code
+   * compilation.
+   *
+   * For high-performance scenarios with multiple concurrent users, the compiler
+   * can be separated into dedicated worker processes to prevent blocking the
+   * main agent during computationally intensive compilation operations.
+   */
   compiler: IAutoBeCompiler;
+
+  /**
+   * Optional conversation and development histories for session continuation.
+   *
+   * Enables resuming previous vibe coding sessions by providing the
+   * chronological record of past conversations, development activities, and
+   * generated artifacts. When provided, the agent reconstructs its internal
+   * state from these histories, allowing seamless continuation of development
+   * work.
+   *
+   * This capability supports iterative development workflows where users can
+   * return to modify, enhance, or extend previously generated applications
+   * while maintaining full context of earlier decisions and implementations.
+   */
   histories?: AutoBeHistory[] | undefined;
+
+  /**
+   * Optional behavioral configuration for localization and context.
+   *
+   * Customizes the agent's communication style, language preferences, and
+   * geographical context to provide personalized vibe coding experiences.
+   * Configuration includes locale settings for internationalized responses and
+   * timezone information for temporal context awareness.
+   *
+   * These settings influence how the agent communicates with users, interprets
+   * regional requirements (such as regulatory considerations), and handles
+   * time-sensitive operations throughout the development process.
+   */
   config?: IAutoBeConfig | undefined;
 }

package/src/structures/IAutoBeVendor.ts

@@ -1,47 +1,89 @@
 import OpenAI from "openai";
 
 /**
- * LLM service vendor for Agentica Chat.
+ * Interface representing AI vendor configuration for the AutoBeAgent.
  *
- * `IAgenticaVendor` is a type represents an LLM (Large Language Model) vendor
- * of the {@link AutoBeAgent}.
+ * Defines the connection parameters and settings required to integrate with AI
+ * service providers that power the vibe coding pipeline. While utilizing the
+ * OpenAI SDK as the connection interface, this configuration supports various
+ * LLM vendors beyond OpenAI through flexible endpoint and authentication
+ * configuration, enabling integration with Claude, DeepSeek, Meta Llama, and
+ * other providers that follow OpenAI-compatible API patterns.
  *
- * Currently, {@link AutoBeAgent} supports OpenAI SDK. However, it does not mean
- * that you can use only OpenAI's GPT model in the {@link AutoBeAgent}. The
- * OpenAI SDK is just a connection tool to the LLM vendor's API, and you can use
- * other LLM vendors by configuring its `baseURL` and API key.
+ * The vendor configuration determines the AI capabilities available throughout
+ * the entire automated development workflow, from requirements analysis and
+ * database design through API specification, testing, and final implementation.
+ * Different vendors may offer varying performance characteristics, cost
+ * structures, and feature support that can be optimized for specific vibe
+ * coding needs.
  *
- * Therefore, if you want to use another LLM vendor like Claude or Gemini,
- * please configure the `baseURL` to the {@link api}, and set
- * {@link IAutoBeProps.model schema model} as "cluade" or "gemini".
+ * Concurrent request management is built-in to prevent API rate limiting and
+ * optimize resource utilization across multiple development phases and parallel
+ * operations within the vibe coding pipeline.
  *
  * @author Samchon
  */
 export interface IAutoBeVendor {
-  /** OpenAI API instance. */
+  /**
+   * OpenAI SDK instance configured for the target AI vendor.
+   *
+   * Provides the API connection interface used by the AutoBeAgent to
+   * communicate with AI services. While this uses the OpenAI SDK, it can be
+   * configured to connect with various LLM providers by setting the appropriate
+   * `baseURL` and authentication credentials. The SDK serves as a universal
+   * connector that abstracts the underlying API communication protocols.
+   *
+   * For non-OpenAI vendors, configure the SDK with the vendor's API endpoint
+   * and authentication requirements to enable seamless integration with the
+   * vibe coding system.
+   */
   api: OpenAI;
 
   /**
-   * Chat model to be used.
+   * Specific model identifier to use for AI operations.
+   *
+   * Specifies the exact model name or identifier that should be used for vibe
+   * coding tasks. Supports both official OpenAI chat models and custom model
+   * identifiers for third-party hosting services, cloud providers, or
+   * alternative LLM vendors. The model choice significantly impacts the
+   * quality, performance, and cost of the automated development process.
    *
-   * `({}) & string` means to support third party hosting cloud(eg. openRouter,
-   * aws)
+   * Examples include "gpt-4", "gpt-3.5-turbo" for OpenAI, or vendor-specific
+   * identifiers like "claude-3-sonnet", "deepseek-chat-v3", "llama3.3-70b" when
+   * using alternative providers through compatible APIs.
    */
   model: OpenAI.ChatModel | ({} & string);
 
-  /** Options for the request. */
+  /**
+   * Optional request configuration for API calls.
+   *
+   * Additional request options that will be applied to all API calls made
+   * through the OpenAI SDK. This can include custom headers, timeouts, retry
+   * policies, or other HTTP client configuration that may be required for
+   * specific vendor integrations or enterprise environments.
+   *
+   * These options provide fine-grained control over the API communication
+   * behavior and can be used to optimize performance or meet specific
+   * infrastructure requirements.
+   */
   options?: OpenAI.RequestOptions | undefined;
 
   /**
-   * Number of concurrent requests allowed.
+   * Maximum number of concurrent API requests allowed.
+   *
+   * Controls the concurrency level for AI API calls to prevent rate limiting,
+   * manage resource consumption, and optimize system performance. The vibe
+   * coding pipeline may make multiple parallel requests during development
+   * phases, and this setting ensures controlled resource utilization.
    *
-   * If you configure this property, {@link AutoBeAgent} will constrain the
-   * number of concurrent requests to the LLM vendor. If you want to share the
-   * semaphore instance with other agents, you can directly assign the
-   * {@link Semaphore} instance to this property.
+   * A reasonable default provides balanced performance while respecting typical
+   * API rate limits. Lower values reduce resource consumption but may slow
+   * development progress, while higher values can improve performance but risk
+   * hitting rate limits or overwhelming the AI service.
    *
-   * Otherwise, it will not limit the number of concurrent requests, and the
-   * {@link AutoBeAgent} will send requests asynchronously without any limit.
+   * Set to undefined to disable concurrency limiting, allowing unlimited
+   * parallel requests (use with caution based on your API limits and
+   * infrastructure capacity).
    *
    * @default 16
    */

package/src/utils/backoffRetry.ts

@@ -0,0 +1,84 @@
+import { RetryOptions } from "./types/BackoffOptions";
+
+/**
+ * @param fn Function to Apply the retry logic.
+ * @param maxRetries How many time to try. Max Retry is 5.
+ * @returns
+ */
+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;
+}
+
+function isRetryError(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
+  if (
+    (typeof error?.status === "number" && error.status >= 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;
+  }
+
+  return false;
+}

package/src/utils/types/BackoffOptions.ts

@@ -0,0 +1,15 @@
+/*
+ * Random exponential backoff retry utility for handling rate limits
+ */
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 5) */
+  maxRetries: number;
+  /** Base delay in milliseconds (default: 2000) */
+  baseDelay: number;
+  /** Maximum delay in milliseconds (default: 60_000) */
+  maxDelay: number;
+  /** Jitter factor for randomization (0-1, default: 0.3) */
+  jitter: number;
+  /** Function to determine if error should trigger retry (default: isRetryError) */
+  handleError: (error: any) => boolean;
+}