@autobe/agent 0.9.1 → 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,27 +16,31 @@ 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[];
   }
 
   /**
    * Represents a test scenario for a single API operation.
    *
-   * This interface extends `AutoBeOpenApi.IEndpoint`, inheriting its HTTP
-   * method and path information, and adds two key properties:
-   *
-   * - `draft`: A free-form, human-readable test scenario description for the API
-   *   endpoint.
-   * - `dependsOn`: A list of other API endpoints that must be invoked beforehand
-   *   in order to prepare the context for this test. Each dependency includes
-   *   the purpose of the dependency.
-   *
-   * This structure is intended to help organize test specifications for complex
-   * workflows and ensure that all prerequisites are explicitly declared.
+   * This interface defines a structured, user-centric test draft that includes
+   * a descriptive function name, a detailed scenario draft, and logical
+   * dependencies on other endpoints required for context or setup.
    */
   export interface IScenario {
     /**
@@ -44,7 +48,7 @@ export namespace IAutoBeTestScenarioApplication {
      * be tested. This should include both successful and failure scenarios,
      * business rule validations, edge cases, and any sequence of steps
      * necessary to perform the test. A subsequent agent will use this draft to
-     * generate multiple test scenarios.
+     * generate multiple concrete test cases.
      */
     draft: string;
 
@@ -109,20 +113,26 @@ export namespace IAutoBeTestScenarioApplication {
     functionName: string;
 
     /**
-     * A list of other API endpoints that must be executed before this test
-     * scenario. This helps express dependencies such as data creation or
-     * authentication steps required to reach the intended test state.
+     * A list of other API endpoints that this scenario logically depends on.
+     *
+     * These dependencies represent context or prerequisite conditions, such as
+     * authentication, resource creation, or data setup, that are relevant to
+     * the test. This list is not a strict execution order — if ordering is
+     * important, it must be described explicitly in the `purpose`.
      */
-    dependsOn: IDependsOn[];
+    dependencies: IDependencies[];
   }
 
-  export interface IDependsOn {
-    /** Target API endpoint that must be executed before the main operation. */
+  export interface IDependencies {
+    /** Target API endpoint that this scenario depends on. */
     endpoint: AutoBeOpenApi.IEndpoint;
 
     /**
-     * A concise exscenarioation of why this API call is required before
-     * executing the test for the main operation.
+     * A concise explanation of why this API call is relevant or required for
+     * the main test scenario.
+     *
+     * This should describe the contextual or setup role of the dependency, such
+     * as creating necessary data or establishing user authentication.
      *
      * Example: "Creates a category so that a product can be linked to it during
      * creation."

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

@@ -1,4 +1,7 @@
+import { AutoBeOpenApi } from "@autobe/interface";
+
 export interface IAutoBeTestScenarioArtifacts {
+  document: AutoBeOpenApi.IDocument;
   sdk: Record<string, string>;
   dto: Record<string, string>;
   e2e: Record<string, string>;

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,51 +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 = (
-  artifacts: IAutoBeTestScenarioArtifacts,
+  func: IAutoBeTestFunction,
+  failure: IAutoBeTypeScriptCompileResult.IFailure,
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
-> => {
-  return [
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_CORRECT,
-    },
-    {
-      id: v4(),
-      created_at: new Date().toISOString(),
-      type: "assistantMessage",
-      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",
-        "### 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,53 +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: "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"),
+      type: "systemMessage",
+      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/structures/IAutoBeProps.ts

@@ -1,6 +1,11 @@
-import { AutoBeHistory, IAutoBeCompiler } from "@autobe/interface";
+import {
+  AutoBeHistory,
+  IAutoBeCompiler,
+  IAutoBeTokenUsageJson,
+} from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 
+import { AutoBeTokenUsage } from "../context/AutoBeTokenUsage";
 import { IAutoBeConfig } from "./IAutoBeConfig";
 import { IAutoBeVendor } from "./IAutoBeVendor";
 
@@ -101,4 +106,15 @@ export interface IAutoBeProps<Model extends ILlmSchema.Model> {
    * time-sensitive operations throughout the development process.
    */
   config?: IAutoBeConfig | undefined;
+
+  /**
+   * Token usage information.
+   *
+   * You can start token usage tracing by assigning this property.
+   *
+   * If you assign {@link IAutoBeTokenUsageJson} value, the token usage tracing
+   * would be from the value. Otherwise you assign the {@link AutoBeTokenUsage}
+   * typed instance, the tracing would be binded to the instance.
+   */
+  tokenUsage?: IAutoBeTokenUsageJson | AutoBeTokenUsage | undefined;
 }