@autobe/agent 0.9.2 → 0.10.0

package/src/orchestrate/test/structures/IAutoBeTestCorrectApplication.ts

@@ -0,0 +1,126 @@
+export interface IAutoBeTestCorrectApplication {
+  /**
+   * Main entry point for AI Function Call - analyzes compilation errors and
+   * generates corrected E2E test code.
+   *
+   * The AI executes this function to perform the complete error correction
+   * workflow: error-free analysis → compilation error analysis → draft
+   * correction → code review → final corrected implementation. This multi-step
+   * process ensures systematic error resolution while preserving original test
+   * functionality and maintaining code quality.
+   *
+   * The corrector first analyzes the scenario without considering compilation
+   * errors to understand the intended functionality, then incorporates
+   * compilation diagnostics to identify specific issues, and finally produces
+   * corrected code through iterative refinement with comprehensive review and
+   * validation.
+   *
+   * @param props Complete specification for error correction workflow including
+   *   analysis steps, draft implementation, review process, and final code
+   *   generation
+   */
+  rewrite(props: IAutoBeTestCorrectApplication.IProps): void;
+}
+
+export namespace IAutoBeTestCorrectApplication {
+  export interface IProps {
+    /**
+     * Step 1: Initial analysis and understanding without compilation error
+     * context.
+     *
+     * AI analyzes the original test scenario, business requirements, and
+     * intended functionality without being influenced by compilation errors.
+     * This clean analysis establishes a clear understanding of what the test
+     * should accomplish, the expected business workflow, and the correct API
+     * integration patterns.
+     *
+     * This step ensures that error correction doesn't lose sight of the
+     * original test purpose and helps maintain the intended business logic
+     * while addressing technical compilation issues. The AI develops a
+     * comprehensive understanding of the test requirements before diving into
+     * error-specific details.
+     *
+     * Workflow: Scenario understanding → Business logic analysis → Intended
+     * functionality mapping
+     */
+    think_without_compile_error: string;
+
+    /**
+     * Step 2: Compilation error analysis and root cause identification.
+     *
+     * AI re-analyzes the scenario and implementation with full awareness of
+     * compilation errors and diagnostic information. This step involves
+     * systematic examination of error messages, identification of error
+     * patterns, and understanding of how compilation issues relate to the
+     * intended functionality.
+     *
+     * The AI correlates compilation diagnostics with the original requirements
+     * to understand where the implementation diverged from correct TypeScript
+     * usage while maintaining the business logic intent. This analysis forms
+     * the foundation for targeted error correction strategies.
+     *
+     * Workflow: Error diagnostic analysis → Root cause identification →
+     * Correction strategy planning
+     */
+    think_again_with_compile_error: string;
+
+    /**
+     * Step 3: Draft corrected TypeScript E2E test code implementation.
+     *
+     * AI generates the first corrected version of the test code based on error
+     * analysis and correction strategies. This draft addresses all identified
+     * compilation errors while preserving the original business logic and test
+     * workflow. The code must be compilation-error-free and follow all
+     * established conventions.
+     *
+     * The implementation incorporates lessons learned from error analysis to
+     * produce properly typed, syntactically correct code that maintains the
+     * intended test functionality. All type safety requirements and framework
+     * conventions must be followed in this corrected implementation.
+     *
+     * Workflow: Error correction → TypeScript implementation → Functional
+     * preservation Critical: Must resolve all compilation errors while
+     * maintaining original test intent
+     */
+    draft: string;
+
+    /**
+     * Step 4: Code review and correction validation.
+     *
+     * AI performs a comprehensive review of the corrected draft implementation,
+     * validating that all compilation errors have been resolved and that the
+     * code maintains the original functionality. This review examines both
+     * technical correctness and business logic preservation.
+     *
+     * The review process includes verification of TypeScript compilation
+     * compatibility, API integration correctness, test workflow completeness,
+     * and adherence to all quality standards. Any remaining issues or potential
+     * improvements are identified for incorporation into the final
+     * implementation.
+     *
+     * Workflow: Draft validation → Compilation verification → Functionality
+     * review → Quality assessment
+     */
+    review: string;
+
+    /**
+     * Step 5: Final production-ready corrected test code.
+     *
+     * AI produces the final, polished version of the corrected test code
+     * incorporating all review feedback and validation results. This code
+     * represents the completed error correction, guaranteed to compile
+     * successfully while preserving all original test functionality and
+     * business logic.
+     *
+     * The final implementation resolves all compilation issues, maintains
+     * strict type safety, follows all established conventions, and delivers a
+     * production-ready test that accurately validates the intended API
+     * behaviors and user workflows.
+     *
+     * Workflow: Review integration → Final refinement → Production-ready
+     * implementation This is the ultimate deliverable that will replace the
+     * compilation-failed code.
+     */
+    final: string;
+  }
+}

package/src/orchestrate/test/structures/IAutoBeTestFunction.ts

@@ -0,0 +1,10 @@
+import { AutoBeTestScenario } from "@autobe/interface";
+
+import { IAutoBeTestScenarioArtifacts } from "./IAutoBeTestScenarioArtifacts";
+
+export interface IAutoBeTestFunction {
+  artifacts: IAutoBeTestScenarioArtifacts;
+  scenario: AutoBeTestScenario;
+  location: string;
+  script: string;
+}

package/src/orchestrate/test/structures/IAutoBeTestScenarioApplication.ts

@@ -16,10 +16,22 @@ export namespace IAutoBeTestScenarioApplication {
   }
 
   export interface IScenarioGroup {
-    /** Target API endpoint to test. */
+    /**
+     * Target API endpoint to test.
+     *
+     * This must be **unique** across all scenario groups. An endpoint is
+     * identified by its `path` and `method` combination.
+     *
+     * Multiple test scenarios may exist for a single endpoint.
+     */
     endpoint: AutoBeOpenApi.IEndpoint;
 
-    /** Array of test scenarios. */
+    /**
+     * An array of test scenarios associated with the given endpoint.
+     *
+     * Each scenario represents a specific test case for the same `path` and
+     * `method`.
+     */
     scenarios: IScenario[];
   }
 

package/src/orchestrate/test/structures/IAutoBeTestWriteApplication.ts

@@ -0,0 +1,117 @@
+export interface IAutoBeTestWriteApplication {
+  /**
+   * Main entry point for AI Function Call - generates complete E2E test code.
+   *
+   * The AI executes this function to perform the entire test generation
+   * workflow: scenario analysis → draft implementation → code review → final
+   * code production. This structured approach ensures high-quality,
+   * compilation-error-free test code.
+   *
+   * @param props Complete specification for test generation including scenario,
+   *   domain, and implementation steps
+   */
+  write(props: IAutoBeTestWriteApplication.IProps): void;
+}
+
+export namespace IAutoBeTestWriteApplication {
+  export interface IProps {
+    /**
+     * Step 1: Strategic test planning and scenario analysis.
+     *
+     * AI analyzes the given test scenario and creates a comprehensive
+     * implementation strategy. This planning phase is crucial for generating
+     * well-structured, maintainable test code. The AI must define test
+     * methodology, data preparation, execution flow, and validation logic
+     * before proceeding to code implementation.
+     *
+     * Workflow: Input scenario → Strategic analysis → Detailed test plan
+     */
+    scenario: string;
+
+    /**
+     * Step 2: Functional domain classification for test organization.
+     *
+     * AI determines the appropriate domain category based on the scenario
+     * analysis. This classification drives file structure, test categorization,
+     * and logical grouping. The domain must be a single, lowercase word that
+     * represents the primary API resource.
+     *
+     * Workflow: Scenario analysis → Domain identification → Test organization
+     * structure
+     */
+    domain: string;
+
+    /**
+     * Step 3: Initial TypeScript E2E test code implementation.
+     *
+     * AI generates the first working version of the test code based on the
+     * strategic plan. This draft must be compilation-error-free and follow
+     *
+     * @nestia/e2e framework conventions. The code should implement all planned
+     * test scenarios with proper async/await patterns, type safety, and
+     * comprehensive error handling.
+     *
+     * Workflow: Strategic plan → TypeScript implementation → Functional test
+     * code
+     *
+     * Critical: NO import statements, start directly with 'export async function'
+     */
+    draft: string;
+
+    /**
+     * Step 4: Code review and quality assessment.
+     *
+     * AI performs a thorough review of the draft implementation, examining:
+     *
+     * **Compilation & Syntax:**
+     *
+     * - TypeScript compilation errors and type mismatches
+     * - Syntax errors and missing semicolons/brackets
+     * - Correct function signatures and parameter types
+     *
+     * **Framework Compliance:**
+     *
+     * - @nestia/e2e framework conventions adherence
+     * - Proper API SDK function calling patterns
+     * - Correct use of typia.assert() and TestValidator functions
+     *
+     * **Business Logic & Test Coverage:**
+     *
+     * - Complete workflow implementation (authentication → data setup → main test
+     *   → validation)
+     * - Realistic business scenarios and user journeys
+     * - Edge case handling and error condition testing
+     * - Proper data dependencies and cleanup procedures
+     *
+     * **Code Quality & Security:**
+     *
+     * - Type safety violations (any, @ts-ignore, etc.)
+     * - Variable naming and code organization
+     * - Performance considerations and resource management
+     * - Security best practices in test data generation
+     *
+     * Workflow: Draft code → Systematic analysis → Specific improvement
+     * recommendations
+     *
+     * The review must identify concrete issues with line-by-line feedback and
+     * provide actionable solutions for each problem discovered.
+     */
+    review: string;
+
+    /**
+     * Step 5: Final production-ready test code.
+     *
+     * AI produces the final, polished version of the test code incorporating
+     * all review feedback. This code represents the completed test
+     * implementation, ready for production deployment. All identified issues
+     * must be resolved, and the code must meet the highest quality standards.
+     *
+     * Workflow: Review feedback → Code refinement → Production-ready
+     * implementation
+     *
+     * This is the ultimate deliverable that will be used in the actual test
+     * suite.
+     */
+    final: string;
+  }
+}

package/src/orchestrate/test/structures/IAutoBeTestWriteResult.ts

@@ -0,0 +1,9 @@
+import { AutoBeTestScenario, AutoBeTestWriteEvent } from "@autobe/interface";
+
+import { IAutoBeTestScenarioArtifacts } from "./IAutoBeTestScenarioArtifacts";
+
+export interface IAutoBeTestWriteResult {
+  scenario: AutoBeTestScenario;
+  artifacts: IAutoBeTestScenarioArtifacts;
+  event: AutoBeTestWriteEvent;
+}

package/src/orchestrate/test/transformTestCorrectHistories.ts

@@ -1,79 +1,46 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
+import { IAutoBeTypeScriptCompileResult } from "@autobe/interface";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptConstant";
-import { IAutoBeTestScenarioArtifacts } from "./structures/IAutoBeTestScenarioArtifacts";
+import { IAutoBeTestFunction } from "./structures/IAutoBeTestFunction";
+import { transformTestWriteHistories } from "./transformTestWriteHistories";
 
 export const transformTestCorrectHistories = (
-  code: string,
-  artifacts: IAutoBeTestScenarioArtifacts,
-  diagnostics: string[],
+  func: IAutoBeTestFunction,
+  failure: IAutoBeTypeScriptCompileResult.IFailure,
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
-> => {
-  return [
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_WRITE,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "assistantMessage",
-      text: [
-        "# Original Code",
-        "```typescript",
-        code,
-        "```",
-        "",
-        "# Compile Errors",
-        "Fix the compilation error in the provided code.",
-        ...diagnostics,
-      ].join("\n"),
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_CORRECT,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: [
-        "You are the world's best TypeScript compiler error fixer.",
-        "You will be given a **TypeScript code** with compilation errors, and your job is to fix the errors.",
-        "",
-        "# Rules",
-        "- Follow the base E2E test style strictly. Never use other frameworks like Jest or Mocha.",
-        "- Use `TestValidator.equals(...)` and `typia.assert(...)` to verify results.",
-        "- Use `api.functional.XXX` for all API calls. These are defined in API Files.",
-        "- Use helper functions like `generate_random_xxx(...)` **only if** they already exist in the base test imports.",
-        "- Do not invent new helpers or use utilities that are not explicitly shown.",
-        "- Keep all tests deterministic and reliable.",
-        "",
-        "# File References",
-        `The import statements are automatically inserted based on the AST, which provides all necessary types and SDKs required.`,
-        `Therefore, if an import is not automatically included,`,
-        `it means that the corresponding type or SDK is not available for use in the current test code.`,
-        `You must solve the issue using only the provided SDK and types.`,
-        "",
-        "## API Files",
-        "```typescript",
-        JSON.stringify(artifacts.sdk),
-        "```",
-        "",
-        "## DTO Files",
-        "```typescript",
-        JSON.stringify(artifacts.dto),
-        "```",
-        "",
-        "Now Fix the E2E test function based on the given error information.",
-        "Only output a single `async function` named `test_api_{...}`. No explanation, no commentary.",
-      ].join("\n"),
-    },
-  ];
-};
+> => [
+  ...transformTestWriteHistories(func.scenario, func.artifacts),
+  {
+    id: v4(),
+    created_at: new Date().toISOString(),
+    type: "assistantMessage",
+    text: [
+      "## Generated TypeScript Code",
+      "```typescript",
+      func.script,
+      "```",
+      "",
+      "## Compile Errors",
+      "Fix the compilation error in the provided code.",
+      "",
+      "```json",
+      JSON.stringify(failure.diagnostics),
+      "```",
+    ].join("\n"),
+  },
+  {
+    id: v4(),
+    created_at: new Date().toISOString(),
+    type: "systemMessage",
+    text: AutoBeSystemPromptConstant.TEST_CORRECT.replace(
+      "{{API_DTO_SCHEMAS}}",
+      transformTestWriteHistories.structures(func.artifacts),
+    ).replace(
+      "{{API_SDK_FUNCTIONS}}",
+      transformTestWriteHistories.functional(func.artifacts),
+    ),
+  },
+];

package/src/orchestrate/test/transformTestWriteHistories.ts

@@ -1,65 +1,107 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
 import { AutoBeTestScenario } from "@autobe/interface";
+import { StringUtil, transformOpenApiDocument } from "@autobe/utils";
+import {
+  HttpMigration,
+  IHttpMigrateApplication,
+  OpenApi,
+} from "@samchon/openapi";
+import typia from "typia";
 import { v4 } from "uuid";
 
 import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptConstant";
 import { IAutoBeTestScenarioArtifacts } from "./structures/IAutoBeTestScenarioArtifacts";
 
-export const transformTestWriteHistories = (props: {
-  scenario: AutoBeTestScenario;
-  artifacts: IAutoBeTestScenarioArtifacts;
-}): Array<
-  IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
-> => {
+export function transformTestWriteHistories(
+  scenario: AutoBeTestScenario,
+  artifacts: IAutoBeTestScenarioArtifacts,
+): Array<IAgenticaHistoryJson.ISystemMessage> {
   return [
     {
       id: v4(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_WRITE,
+      text: AutoBeSystemPromptConstant.TEST_WRITE.replace(
+        "{{AutoBeTestScenario}}",
+        JSON.stringify(typia.llm.parameters<AutoBeTestScenario, "llama">()),
+      ),
     },
     {
       id: v4(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_VALIDATOR,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_TYPESCRIPT_SYNTAX,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "assistantMessage",
-      text: [
-        "Here is the list of input material composition.",
-        "",
-        "Make e2e test functions based on the following information.",
-        "",
-        "## Secnario Plan",
-        "```json",
-        JSON.stringify(props.scenario),
-        "```",
-        "",
-        "## DTO Definitions",
-        "```json",
-        JSON.stringify(props.artifacts.dto),
-        "```",
-        "",
-        "## API (SDK) Functions",
-        "```json",
-        JSON.stringify(props.artifacts.sdk),
-        "```",
-        "",
-        "## E2E Mockup Functions",
-        "```json",
-        JSON.stringify(props.artifacts.e2e),
-        "```",
-        "",
-      ].join("\n"),
+      text: StringUtil.trim`
+        Here is the list of input material composition.
+
+        Make e2e test functions based on the following information.
+
+        ## Scenario Plan
+
+        Here is the scenario plan what you have to implement.
+
+        \`\`\`json
+        ${JSON.stringify(scenario)}
+        \`\`\`
+
+        ## DTO Definitions
+
+        You can use these DTO definitions.
+
+        Never use the DTO definitions that are not listed here.
+
+        ${transformTestWriteHistories.structures(artifacts)}
+
+        ## API (SDK) Functions
+
+        You can use these API functions.
+
+        Never use the functions that are not listed here.
+
+        ${transformTestWriteHistories.functional(artifacts)}
+
+        ## E2E Mockup Functions
+
+        Just reference, and never follow this code as it is.
+
+        \`\`\`json
+        ${JSON.stringify(artifacts.e2e)}
+        \`\`\`
+      `,
     },
   ];
-};
+}
+export namespace transformTestWriteHistories {
+  export function structures(artifacts: IAutoBeTestScenarioArtifacts): string {
+    return StringUtil.trim`
+      ${Object.keys(artifacts.document.components.schemas)
+        .map((k) => `- ${k}`)
+        .join("\n")}
+
+      \`\`\`json
+      ${JSON.stringify(artifacts.dto)}
+      \`\`\`
+    `;
+  }
+
+  export function functional(artifacts: IAutoBeTestScenarioArtifacts): string {
+    const document: OpenApi.IDocument = transformOpenApiDocument(
+      artifacts.document,
+    );
+    const app: IHttpMigrateApplication = HttpMigration.application(document);
+    return StringUtil.trim`
+      Method | Path | Function Accessor
+      -------|------|-------------------
+      ${app.routes
+        .map((r) =>
+          [r.method, r.path, `api.functional.${r.accessor.join(".")}`].join(
+            " | ",
+          ),
+        )
+        .join("\n")}
+
+      \`\`\`json
+      ${JSON.stringify(artifacts.sdk)}
+      \`\`\`
+    `;
+  }
+}

package/src/structures/IAutoBeConfig.ts

@@ -60,4 +60,13 @@ export interface IAutoBeConfig {
    * @default System timezone or "UTC" if unavailable
    */
   timezone?: string;
+
+  /**
+   * Backoff strategy for retrying failed operations.
+   *
+   * Defines the logic for retrying failed operations when the agent encounters
+   * errors. This includes retrying function calls, API requests, and other
+   * operations that may fail due to temporary issues.
+   */
+  backoffStrategy?: (props: { count: number; error: unknown }) => number;
 }

package/src/utils/backoffRetry.ts

@@ -1,42 +1,23 @@
-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);
+export function randomBackoffStrategy(props: {
+  count: number;
+  error: unknown;
+}): number {
+  const { count, error } = props;
+  if (count > 5) {
+    throw error;
+  }
 
-      await new Promise((res) => setTimeout(res, delay));
-    }
+  if (isRetryError(error) === false) {
+    throw error;
   }
 
-  throw lastError;
+  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;
 }
 
 function isRetryError(error: any): boolean {
@@ -80,5 +61,13 @@ function isRetryError(error: any): boolean {
     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/forceRetry.ts

@@ -0,0 +1,13 @@
+export async function forceRetry<T>(
+  task: () => Promise<T>,
+  count: number = 2,
+): Promise<T> {
+  let error: unknown = undefined;
+  for (let i: number = 0; i <= count; ++i)
+    try {
+      return await task();
+    } catch (e) {
+      error = e;
+    }
+  throw error;
+}

package/lib/factory/invertOpenApiDocument.d.ts

@@ -1,3 +0,0 @@
-import { AutoBeOpenApi } from "@autobe/interface";
-import { OpenApi } from "@samchon/openapi";
-export declare function invertOpenApiDocument(document: OpenApi.IDocument): AutoBeOpenApi.IDocument;