@autobe/agent 0.9.1 → 0.9.2

package/src/orchestrate/test/orchestrateTestCorrect.ts

@@ -112,7 +112,12 @@ async function step<Model extends ILlmSchema.Model>(
   // COMPILE TEST CODE
   const result: IAutoBeTypeScriptCompilerResult =
     await ctx.compiler.typescript.compile({
-      files: entireFiles,
+      files: {
+        ...entireFiles,
+        ...testFiles
+          .map((el) => ({ [el.location]: el.content }))
+          .reduce((acc, cur) => Object.assign(acc, cur), {}),
+      },
     });
 
   if (result.type === "success") {
@@ -213,14 +218,29 @@ async function step<Model extends ILlmSchema.Model>(
           step: ctx.state().interface?.step ?? 0,
         });
 
-        return { location: filename, content: code, scenario: scenario };
+        return {
+          location: filename,
+          content: response.content,
+          scenario: scenario,
+        };
       },
     ),
   );
 
   return step(
     ctx,
-    entireFiles,
+    Object.entries(entireFiles)
+      .map(([filename, content]) => {
+        const overwritten = validatedFiles.find(
+          (el) => el.location === filename,
+        );
+        return overwritten
+          ? { [overwritten.location]: overwritten.content }
+          : {
+              [filename]: content,
+            };
+      })
+      .reduce((acc, cur) => Object.assign(acc, cur), {}),
     testFiles.map((f) => {
       const validated = validatedFiles.find((v) => v.location === f.location);
       return validated ? validated : f;
@@ -253,13 +273,34 @@ async function process<Model extends ILlmSchema.Model>(
     scenario,
   );
 
+  const lines = code.split("\n").map((line, num, arr) => {
+    const start = arr
+      .slice(0, num)
+      .map((el) => el.length + 1)
+      .reduce((acc, cur) => acc + cur, 0);
+    return {
+      line: num + 1,
+      text: line,
+      start: start,
+      end: start + line.length + 1, // exclusive
+    };
+  });
+
   const agentica = new MicroAgentica({
     model: ctx.model,
     vendor: { ...ctx.vendor },
     config: {
       ...(ctx.config ?? {}),
     },
-    histories: transformTestCorrectHistories(artifacts),
+    histories: transformTestCorrectHistories(
+      code,
+      artifacts,
+      diagnostics.map((diagnostic) =>
+        diagnostic.start === undefined || diagnostic.length === undefined
+          ? ""
+          : formatDiagnostic(code, lines, diagnostic),
+      ),
+    ),
     controllers: [
       createApplication({
         model: ctx.model,
@@ -275,38 +316,7 @@ async function process<Model extends ILlmSchema.Model>(
   await randomBackoffRetry(async () => {
     await agentica.conversate(
       [
-        "Fix the compilation error in the provided code.",
-        "",
-        "## Original Code",
-        "```typescript",
-        code,
-        "```",
-        "",
-        diagnostics.map((diagnostic) => {
-          if (diagnostic.start === undefined || diagnostic.length === undefined)
-            return "";
-
-          const checkDtoRegexp = `Cannot find module '@ORGANIZATION/template-api/lib/structures/IBbsArticleComment' or its corresponding type declarations.`;
-          const [group] = [
-            ...checkDtoRegexp.matchAll(
-              /Cannot find module '(.*lib\/structures\/.*)'/g,
-            ),
-          ];
-
-          const [_, filename] = group ?? [];
-
-          return [
-            "## Error Information",
-            `- Position: Characters ${diagnostic.start} to ${diagnostic.start + diagnostic.length}`,
-            `- Error Message: ${diagnostic.messageText}`,
-            `- Problematic Code: \`${code.substring(diagnostic.start, diagnostic.start + diagnostic.length)}\``,
-            filename
-              ? `The type files located under **/lib/structures are declared in '@ORGANIZATION/PROJECT-api/lib/structures'.\n` +
-                `Note: '@ORGANIZATION/PROJECT-api' must be written exactly as is and should not be replaced.\n`
-              : "",
-          ].join("\n");
-        }),
-        "## Instructions",
+        "# Instructions",
         "1. Focus on the specific error location and message",
         "2. Provide the corrected TypeScript code",
         "3. Ensure the fix resolves the compilation error",
@@ -316,9 +326,160 @@ async function process<Model extends ILlmSchema.Model>(
     );
   });
   if (pointer.value === null) throw new Error("Failed to modify test code.");
+
+  const typeReferences: string[] = Array.from(
+    new Set(
+      Object.keys(artifacts.document.components.schemas).map(
+        (key) => key.split(".")[0]!,
+      ),
+    ),
+  );
+
+  pointer.value.content = pointer.value.content
+    .replace(/^[ \t]*import\b[\s\S]*?;[ \t]*$/gm, "")
+    .trim();
+  pointer.value.content = [
+    `import { TestValidator } from "@nestia/e2e";`,
+    `import typia, { tags } from "typia";`,
+    "",
+    `import api from "@ORGANIZATION/PROJECT-api";`,
+    ...typeReferences.map(
+      (ref) =>
+        `import type { ${ref} } from "@ORGANIZATION/PROJECT-api/lib/structures/${ref}";`,
+    ),
+    "",
+    pointer.value.content,
+  ].join("\n");
+
+  pointer.value.content = pointer.value.content.replaceAll(
+    'string & Format<"uuid">',
+    'string & tags.Format<"uuid">',
+  );
+
   return pointer.value;
 }
 
+function formatDiagnostic(
+  code: string,
+  lines: {
+    line: number; // line number
+    text: string;
+    start: number;
+    end: number; // exclusive
+  }[],
+  diagnostic: IAutoBeTypeScriptCompilerResult.IDiagnostic,
+): string {
+  const { start, length, messageText } = diagnostic;
+  const message = messageText;
+  if (typeof start === "number" && typeof length === "number") {
+    const end = start + length;
+    const problematicCode = code.substring(start, end);
+    const errorLine = lines.find((line) => line.end > start) ?? null;
+    const lineText = errorLine?.text ?? "";
+
+    const hints = getHints(message, lineText);
+
+    function createAdjustedArray(n: number): number[] {
+      let start = n - 2;
+
+      // 시작 값이 음수라면, 0부터 시작해서 5개의 숫자 생성
+      if (start < 0) {
+        start = 0;
+      }
+
+      return Array.from({ length: 5 }, (_, i) => start + i);
+    }
+
+    const errorLines = createAdjustedArray(errorLine?.line ?? 0);
+
+    const context = errorLines
+      .map((num) => {
+        if (num === errorLine?.line) {
+          if (lines[num - 1]) {
+            return `${lines[num - 1]?.text} // <- ERROR LINE (line:${num})`;
+          }
+        }
+        if (lines[num - 1]) {
+          return lines[num - 1]?.text;
+        }
+
+        return null;
+      })
+      .filter((el) => el !== null);
+
+    return [
+      "## Error Information",
+      `- Position: Characters ${start} to ${end}`,
+      `- Error Message: ${message}`,
+      `- Error Lines: \n${
+        context.length
+          ? [
+              "\t```ts", //
+              ...context.map((el) => `\t${el}`),
+              "\t```",
+            ].join("\n")
+          : "(none)"
+      }`,
+      `- Problematic Code: ${problematicCode.length > 0 ? `\`${problematicCode}\`` : "(none)"}`,
+      ...hints.map((hint) => `- Hint: ${hint}`),
+    ].join("\n");
+  }
+  return ["## Error Information", `- Error Message: ${message}`].join("\n");
+}
+
+function getHints(message: string, lineText: string): string[] {
+  const isTestValidator = lineText.includes("TestValidator");
+  const isTypia =
+    message === "Cannot find name 'Format'. Did you mean 'FormData'?";
+  const isJest = message === "Cannot find name 'expect'.";
+  const isCurrying =
+    isTestValidator && message === "Expected 1 arguments, but got 2";
+  const isAssignability =
+    /Argument of type '([^']+)' is not assignable to parameter of type '([^']+)'/.test(
+      message,
+    );
+
+  const hints: string[] = [];
+
+  if (isTypia) {
+    hints.push(
+      "If you want to use typia tags, use `tags.Format` instead of `Format`.",
+    );
+  }
+
+  if (isJest) {
+    hints.push(
+      'Detected invalid `expect` usage. Use `TestValidator.equals("description")(expected)(actual)`.',
+    );
+  }
+
+  if (isCurrying) {
+    hints.push(
+      "`TestValidator.equals` is a curried function and must be called in **three steps**: `title → expected → actual`.",
+    );
+  } else if (isTestValidator) {
+    hints.push(
+      "The second argument `expected` must be assignable from the type of `actual`. Consider swapping the order if you get a type error.",
+    );
+  }
+
+  if (isAssignability && isTestValidator) {
+    const match = lineText
+      .trim()
+      .match(/TestValidator\.equals\("([^"]+)"\)\(([^)]+)\)\(([^)]+)\)/);
+    if (match) {
+      const [, title, expected, actual] = match;
+      if (actual.includes(expected)) {
+        hints.push(
+          `You can try rearranging the order like this: TestValidator.equals("${title}")(${actual})(${expected})`,
+        );
+      }
+    }
+  }
+
+  return hints;
+}
+
 function createApplication<Model extends ILlmSchema.Model>(props: {
   model: Model;
   build: (next: ICorrectTestFunctionProps) => void;

package/src/orchestrate/test/orchestrateTestScenario.ts

@@ -34,7 +34,7 @@ export async function orchestrateTestScenario<Model extends ILlmSchema.Model>(
   let include: AutoBeOpenApi.IOperation[] = Array.from(operations);
 
   do {
-    const matrix = divideArray({ array: include, capacity: 30 });
+    const matrix = divideArray({ array: include, capacity: 5 });
 
     await Promise.all(
       matrix.map(async (_include) => {
@@ -71,7 +71,7 @@ export async function orchestrateTestScenario<Model extends ILlmSchema.Model>(
           endpoint: pg.endpoint,
           draft: plan.draft,
           functionName: plan.functionName,
-          dependencies: plan.dependsOn,
+          dependencies: plan.dependencies,
         } satisfies AutoBeTestScenario;
       });
     }),
@@ -123,7 +123,9 @@ const createHistoryProperties = (
   operations: AutoBeOpenApi.IOperation[],
   include: Pick<AutoBeOpenApi.IOperation, "method" | "path">[],
   exclude: Pick<AutoBeOpenApi.IOperation, "method" | "path">[],
-) => [
+): Array<
+  IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
+> => [
   {
     id: v4(),
     created_at: new Date().toISOString(),
@@ -135,17 +137,29 @@ const createHistoryProperties = (
     created_at: new Date().toISOString(),
     type: "systemMessage",
     text: [
+      "# Operations",
       "Below are the full operations. Please refer to this.",
       "Your role is to draft all test cases for each given Operation.",
       "It is also permissible to write multiple test codes on a single endpoint.",
       "However, rather than meaningless tests, business logic tests should be written and an E2E test situation should be assumed.",
       "",
+      "Please carefully analyze each operation to identify all dependencies required for testing.",
+      "For example, if you want to test liking and then deleting a post,",
+      "you might think to test post creation, liking, and unlike operations.",
+      "However, even if not explicitly mentioned, user registration and login are essential prerequisites.",
+      "Pay close attention to IDs and related values in the API,",
+      "and ensure you identify all dependencies between endpoints.",
+      "",
       "```json",
       JSON.stringify(
         operations.map((el) => ({
           path: el.path,
           method: el.method,
           summary: el.summary,
+          description: el.description,
+          parameters: el.parameters,
+          requestBody: el.requestBody,
+          responseBody: el.responseBody,
         })),
       ),
       "```",

package/src/orchestrate/test/orchestrateTestWrite.ts

@@ -89,6 +89,35 @@ async function process<Model extends ILlmSchema.Model>(
 
   await agentica.conversate("Create e2e test functions.");
   if (pointer.value === null) throw new Error("Failed to create test code.");
+
+  const typeReferences: string[] = Array.from(
+    new Set(
+      Object.keys(artifacts.document.components.schemas).map(
+        (key) => key.split(".")[0]!,
+      ),
+    ),
+  );
+  pointer.value.content = pointer.value.content
+    .replace(/^[ \t]*import\b[\s\S]*?;[ \t]*$/gm, "")
+    .trim();
+  pointer.value.content = [
+    `import { TestValidator } from "@nestia/e2e";`,
+    `import typia, { tags } from "typia";`,
+    "",
+    `import api from "@ORGANIZATION/PROJECT-api";`,
+    ...typeReferences.map(
+      (ref) =>
+        `import type { ${ref} } from "@ORGANIZATION/PROJECT-api/lib/structures/${ref}";`,
+    ),
+    "",
+    pointer.value.content,
+  ].join("\n");
+
+  pointer.value.content = pointer.value.content.replaceAll(
+    'string & Format<"uuid">',
+    'string & tags.Format<"uuid">',
+  );
+
   return pointer.value;
 }
 
@@ -147,8 +176,9 @@ interface ICreateTestCodeProps {
    *
    * ### Critical Requirements
    *
-   * - Must follow the Test Generation Guildelines.
-   * - Must Planning the test code Never occur the typescript compile error.
+   * - Must follow the Test Generation Guidelines.
+   * - Must Planning the test code Never occur the TypeScript compile error.
+   * - NEVER include import statements in planning or implementation.
    *
    * ### Planning Elements:
    *
@@ -176,7 +206,7 @@ interface ICreateTestCodeProps {
    *     4. Test error plans (missing fields, invalid data)
    *     5. Verify database state changes
    *     6. Reconsider the scenario if it doesn't follow the Test Generation
-   *        Guildelines.
+   *        Guidelines.
    */
   scenario: string;
 
@@ -215,16 +245,14 @@ interface ICreateTestCodeProps {
    *
    * ### Technical Implementation Requirements:
    *
-   * #### Import Declarations
-   * ```typescript
-   * import api from "@ORGANIZATION/PROJECT-api";
-   * import { ITargetType } from "@ORGANIZATION/PROJECT-api/lib/structures/[path]";
-   * import { TestValidator } from "@nestia/e2e";
-   * import typia from "typia";
-   * ```
-   * - Must use exact `@ORGANIZATION/PROJECT-api` module path
-   * - Include `@ORGANIZATION` prefix in all API-related imports
-   * - Import specific DTO types from correct structure paths
+   * #### NO IMPORT DECLARATIONS
+   * - NEVER write any import statements
+   * - Start code directly with `export async function`
+   * - All dependencies assumed globally available:
+   *   - `api` for SDK functions
+   *   - `typia` for validation and random data
+   *   - All DTO types (ITargetType, etc.)
+   *   - `TestValidator` for assertions
    *
    * #### Code Quality Standards
    * - Zero TypeScript compilation errors (mandatory)
@@ -235,12 +263,12 @@ interface ICreateTestCodeProps {
    * - Consistent formatting and naming conventions
    *
    * ### Critical Error Prevention
-   * - Verify all import paths are correct and accessible
+   * - Verify all API function signatures and parameter types
    * - Ensure type compatibility between variables and assignments
    * - Include all required object properties and methods
-   * - Validate API function signatures and parameter types
    * - Confirm proper generic type usage
    * - Test async function declarations and Promise handling
+   * - NO IMPORT STATEMENTS ANYWHERE IN CODE
    */
   content: string;
 }

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

@@ -26,17 +26,9 @@ export namespace IAutoBeTestScenarioApplication {
   /**
    * 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 +36,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 +101,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/transformTestCorrectHistories.ts

@@ -5,7 +5,9 @@ import { AutoBeSystemPromptConstant } from "../../constants/AutoBeSystemPromptCo
 import { IAutoBeTestScenarioArtifacts } from "./structures/IAutoBeTestScenarioArtifacts";
 
 export const transformTestCorrectHistories = (
+  code: string,
   artifacts: IAutoBeTestScenarioArtifacts,
+  diagnostics: string[],
 ): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
@@ -14,17 +16,38 @@ export const transformTestCorrectHistories = (
       id: v4(),
       created_at: new Date().toISOString(),
       type: "systemMessage",
-      text: AutoBeSystemPromptConstant.TEST_CORRECT,
+      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",
+        "# 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.",
@@ -32,13 +55,18 @@ export const transformTestCorrectHistories = (
         "- Do not invent new helpers or use utilities that are not explicitly shown.",
         "- Keep all tests deterministic and reliable.",
         "",
-        "## File References",
-        "### API Files",
+        "# 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",
+        "## DTO Files",
         "```typescript",
         JSON.stringify(artifacts.dto),
         "```",

package/src/orchestrate/test/transformTestWriteHistories.ts

@@ -18,6 +18,18 @@ export const transformTestWriteHistories = (props: {
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.TEST_WRITE,
     },
+    {
+      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(),

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;
 }