@autobe/agent 0.25.0 → 0.25.1

package/src/orchestrate/realize/orchestrateRealizeCorrect.ts

@@ -19,6 +19,7 @@ import { IAutoBeRealizeCorrectApplication } from "./structures/IAutoBeRealizeCor
 import { IAutoBeRealizeFunctionFailure } from "./structures/IAutoBeRealizeFunctionFailure";
 import { IAutoBeRealizeScenarioResult } from "./structures/IAutoBeRealizeScenarioResult";
 import { filterDiagnostics } from "./utils/filterDiagnostics";
+import { getRealizeWriteCodeTemplate } from "./utils/getRealizeWriteCodeTemplate";
 import { getRealizeWriteDto } from "./utils/getRealizeWriteDto";
 import { replaceImportStatements } from "./utils/replaceImportStatements";
 
@@ -42,7 +43,9 @@ export async function orchestrateRealizeCorrect<Model extends ILlmSchema.Model>(
   const diagnostics = event.result.diagnostics;
 
   if (
-    event.result.diagnostics.every((d) => !d.file?.startsWith("src/providers"))
+    event.result.diagnostics.every(
+      (d) => !d.file?.startsWith("src/providers"),
+    ) === true
   ) {
     // No diagnostics related to provider functions, stop correcting
     return functions;
@@ -99,7 +102,6 @@ export async function orchestrateRealizeCorrect<Model extends ILlmSchema.Model>(
     ),
     progress,
   );
-
   return orchestrateRealizeCorrect(
     ctx,
     scenarios,
@@ -211,6 +213,23 @@ async function step<Model extends ILlmSchema.Model>(
     enforceFunctionCall: true,
     message: StringUtil.trim`
       Correct the TypeScript code implementation.
+
+      The instruction to write at first was as follows, and the code you received is the code you wrote according to this instruction.
+      When modifying, modify the entire code, but not the import statement.
+
+      Below is template code you wrote:
+      
+      ${getRealizeWriteCodeTemplate({
+        scenario: props.scenario,
+        schemas: ctx.state().interface!.document.components.schemas,
+        operation: props.scenario.operation,
+        authorization: props.authorization ?? null,
+      })}
+
+      Current code is as follows:
+      \`\`\`typescript
+      ${props.function.content}
+      \`\`\`
     `,
   });
 
@@ -218,17 +237,25 @@ async function step<Model extends ILlmSchema.Model>(
     return null;
   }
 
-  pointer.value.revise.final = await replaceImportStatements(ctx, {
+  pointer.value.draft = await replaceImportStatements(ctx, {
     operation: props.scenario.operation,
-    code: pointer.value.revise.final,
+    schemas: ctx.state().interface!.document.components.schemas,
+    code: pointer.value.draft,
     decoratorType: props.authorization?.payload.name,
   });
+  if (pointer.value.revise.final)
+    pointer.value.revise.final = await replaceImportStatements(ctx, {
+      operation: props.scenario.operation,
+      schemas: ctx.state().interface!.document.components.schemas,
+      code: pointer.value.revise.final,
+      decoratorType: props.authorization?.payload.name,
+    });
 
   const event: AutoBeRealizeCorrectEvent = {
     type: "realizeCorrect",
     id: v7(),
     location: props.scenario.location,
-    content: pointer.value.revise.final,
+    content: pointer.value.revise.final ?? pointer.value.draft,
     tokenUsage,
     completed: ++props.progress.completed,
     total: props.progress.total,
@@ -253,7 +280,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
     name: "Write code",
     application,
     execute: {
-      review: (next) => {
+      correct: (next) => {
         props.build(next);
       },
     } satisfies IAutoBeRealizeCorrectApplication,

package/src/orchestrate/realize/orchestrateRealizeWrite.ts

@@ -1,4 +1,5 @@
 import {
+  AutoBeOpenApi,
   AutoBeProgressEventBase,
   AutoBeRealizeAuthorization,
   AutoBeRealizeWriteEvent,
@@ -20,6 +21,7 @@ import { replaceImportStatements } from "./utils/replaceImportStatements";
 export async function orchestrateRealizeWrite<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
   props: {
+    document: AutoBeOpenApi.IDocument;
     totalAuthorizations: AutoBeRealizeAuthorization[];
     authorization: AutoBeRealizeAuthorization | null;
     scenario: IAutoBeRealizeScenarioResult;
@@ -69,17 +71,25 @@ export async function orchestrateRealizeWrite<Model extends ILlmSchema.Model>(
   });
   if (pointer.value === null) throw new Error("Failed to write code.");
 
-  pointer.value.final = await replaceImportStatements(ctx, {
+  pointer.value.draft = await replaceImportStatements(ctx, {
     operation: props.scenario.operation,
-    code: pointer.value.final,
+    schemas: props.document.components.schemas,
+    code: pointer.value.draft,
     decoratorType: props.authorization?.payload.name,
   });
+  if (pointer.value.revise.final)
+    pointer.value.revise.final = await replaceImportStatements(ctx, {
+      operation: props.scenario.operation,
+      schemas: props.document.components.schemas,
+      code: pointer.value.revise.final,
+      decoratorType: props.authorization?.payload.name,
+    });
 
   const event: AutoBeRealizeWriteEvent = {
     type: "realizeWrite",
     id: v7(),
     location: props.scenario.location,
-    content: pointer.value.final,
+    content: pointer.value.revise.final ?? pointer.value.draft,
     tokenUsage,
     completed: ++props.progress.completed,
     total: props.progress.total,
@@ -105,7 +115,7 @@ function createController<Model extends ILlmSchema.Model>(props: {
     name: "Write code",
     application,
     execute: {
-      coding: (next) => {
+      write: (next) => {
         props.build(next);
       },
     } satisfies IAutoBeRealizeWriteApplication,

package/src/orchestrate/realize/structures/IAutoBeRealizeCorrectApplication.ts

@@ -1,45 +1,70 @@
 export interface IAutoBeRealizeCorrectApplication {
   /**
-   * Reviews and corrects TypeScript compilation errors.
+   * Systematically analyze and correct TypeScript compilation errors.
    *
-   * Fixes TypeScript compilation errors while preserving original business
-   * logic, applying minimal intervention principle.
+   * Implements a three-phase workflow (think → draft → revise) that balances
+   * efficiency for simple errors with thoroughness for complex problems.
    *
-   * @param props Properties containing the multi-phase error correction process
+   * @param props Three-phase correction properties
    */
-  review: (props: IAutoBeRealizeCorrectApplication.IProps) => void;
+  correct(props: IAutoBeRealizeCorrectApplication.IProps): void;
 }
 
 export namespace IAutoBeRealizeCorrectApplication {
-  /**
-   * Properties for error correction following Chain of Thinking (CoT).
-   *
-   * All phases are wrapped in a `revise` object for systematic error
-   * resolution.
-   */
   export interface IProps {
-    /** Revision process containing all error correction phases. */
-    revise: IRevise;
-  }
-
-  export interface IRevise {
-    /** 
-     * Step 1: TypeScript compilation error analysis and resolution strategy.
-     * Analyzes TypeScript compiler diagnostics (error codes, messages) to understand
-     * type mismatches, missing properties, nullable conflicts, and other compilation issues.
+    /**
+     * Initial error analysis and correction strategy.
+     *
+     * Analyzes TypeScript compilation errors to understand:
+     *
+     * - Error patterns and root causes
+     * - Required fixes and their impact
+     * - Whether quick fixes or deep refactoring is needed
+     * - Prisma schema and API contract constraints
      */
-    errorAnalysis?: string;
+    think: string;
 
-    /** Step 2: Provider function implementation plan. */
-    plan?: string;
+    /**
+     * First correction attempt.
+     *
+     * Implements the initial fixes identified in the think phase. For simple
+     * errors (typos, missing imports), this may be the final solution. Complex
+     * errors may require further refinement.
+     */
+    draft: string;
 
-    /** Step 3: Relevant Prisma schema definitions. */
-    prismaSchemas?: string;
+    /**
+     * Revision and finalization phase.
+     *
+     * Reviews the draft corrections and produces the final, error-free code
+     * that maintains all business requirements.
+     */
+    revise: IReviseProps;
+  }
 
-    /** Step 4: Refined version with improved completeness. */
-    review?: string;
+  export interface IReviseProps {
+    /**
+     * Correction review and validation.
+     *
+     * Analyzes the draft corrections to ensure:
+     *
+     * - All TypeScript errors are resolved
+     * - Business logic remains intact
+     * - AutoBE coding standards are maintained
+     * - No new errors are introduced
+     * - Performance and security are preserved
+     */
+    review: string;
 
-    /** Step 5: Final complete TypeScript function implementation. */
-    final: string;
+    /**
+     * Final error-free implementation.
+     *
+     * The complete, corrected code that passes all TypeScript compilation
+     * checks.
+     *
+     * Returns `null` if the draft corrections are sufficient and need no
+     * further changes.
+     */
+    final: string | null;
   }
 }

package/src/orchestrate/realize/structures/IAutoBeRealizeWriteApplication.ts

@@ -1,55 +1,66 @@
 export interface IAutoBeRealizeWriteApplication {
   /**
-   * Generates provider function implementation through multi-phase development.
+   * Generate complete provider function implementation using Chain of Thinking.
    *
-   * This method implements a systematic approach to generate NestJS provider
-   * functions that handle business logic for API operations. It follows a
-   * schema-first approach with multiple refinement phases to ensure type-safe,
-   * error-free code generation.
+   * Follows a 3-phase process: plan → draft → revise.
    *
-   * The generation process includes:
+   * Ensures type safety, proper Prisma usage, and API contract compliance.
    *
-   * 1. Strategic planning based on Prisma schema analysis
-   * 2. Schema definition for relevant models
-   * 3. Review and refinement for completeness
-   * 4. Final implementation with all validations and type safety
-   *
-   * @param next Properties containing the multi-phase implementation plan and
-   *   code
+   * @param props Chain of Thinking properties for implementation
    */
-  coding: (next: IAutoBeRealizeWriteApplication.IProps) => void;
+  write(props: IAutoBeRealizeWriteApplication.IProps): void;
 }
 
 export namespace IAutoBeRealizeWriteApplication {
-  /**
-   * Properties for the Realize Write Application following Chain of Thinking
-   * (CoT).
-   *
-   * Each field represents a distinct phase in the implementation process.
-   * Detailed guidelines are in REALIZE_WRITE.md.
-   */
   export interface IProps {
     /**
-     * Step 1 - Planning Phase (CoT: Initial Reasoning)
-     *
-     * Strategic plan following SCHEMA-FIRST APPROACH:
-     *
-     * 1. Verify Prisma schema fields (list existing and non-existing)
-     * 2. Plan field usage in operations
-     * 3. Plan type conversions and nullable handling
-     * 4. Define implementation approach with error handling
+     * Implementation plan and strategy.
      *
-     * See REALIZE_WRITE.md for detailed requirements.
+     * Analyzes the provider function requirements, identifies related Prisma
+     * schemas, and outlines the implementation approach. Includes schema
+     * validation and API contract verification.
      */
     plan: string;
 
-    /** Step 2 - Relevant Prisma schema models and fields */
-    prismaSchemas: string;
+    /**
+     * Initial implementation draft.
+     *
+     * The first complete implementation attempt based on the plan. May contain
+     * areas that need refinement in the review phase.
+     */
+    draft: string;
+
+    /**
+     * Revision and finalization phase.
+     *
+     * Reviews the draft implementation and produces the final code with all
+     * improvements and corrections applied.
+     */
+    revise: IReviseProps;
+  }
 
-    /** Step 3 - Refined version with real operations */
+  export interface IReviseProps {
+    /**
+     * Review and improvement suggestions.
+     *
+     * Identifies areas for improvement in the draft code, including:
+     *
+     * - Type safety enhancements
+     * - Prisma query optimizations
+     * - Null/undefined handling corrections
+     * - Authentication/authorization improvements
+     * - Error handling refinements
+     */
     review: string;
 
-    /** Step 4 - Final implementation See REALIZE_WRITE.md for requirements */
-    final: string;
+    /**
+     * Final implementation code.
+     *
+     * The complete, production-ready implementation with all review suggestions
+     * applied.
+     *
+     * Returns `null` if the draft is already perfect and needs no changes.
+     */
+    final: string | null;
   }
 }

package/src/orchestrate/realize/utils/InternalFileSystem.ts

@@ -7,6 +7,6 @@ export namespace InternalFileSystem {
   export const DEFAULT = [
     "src/providers/authorize/jwtAuthorize.ts",
     "src/MyGlobal.ts",
-    "src/util/toISOStringSafe.ts",
+    "src/utils/toISOStringSafe.ts",
   ];
 }

package/src/orchestrate/realize/utils/getRealizeWriteCodeTemplate.ts

@@ -20,9 +20,9 @@ import { getRealizeWriteImportStatements } from "./getRealizeWriteImportStatemen
  *   import { MyGlobal } from "../MyGlobal";
  *   // ... other imports
  *
- *   async function post__users_create(
+ *   async function post__users_create(props: {
  *     body: IUserCreateRequest
- *   ): Promise<IUserResponse> {
+ *   }): Promise<IUserResponse> {
  *     ...
  *   }
  *   ```;
@@ -32,35 +32,31 @@ import { getRealizeWriteImportStatements } from "./getRealizeWriteImportStatemen
  * @param authorization - Authorization context if endpoint is authenticated
  * @returns Complete TypeScript code template as a formatted string
  */
-export function getRealizeWriteCodeTemplate(
-  scenario: IAutoBeRealizeScenarioResult,
-  operation: AutoBeOpenApi.IOperation,
-  authorization: AutoBeRealizeAuthorization | null,
-): string {
+export function getRealizeWriteCodeTemplate(props: {
+  scenario: IAutoBeRealizeScenarioResult;
+  operation: AutoBeOpenApi.IOperation;
+  schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  authorization: AutoBeRealizeAuthorization | null;
+}): string {
   // Collect all function parameters in order
   const functionParameters: string[] = [];
 
   // Add authentication parameter if needed (e.g., user: IUser, admin: IAdmin)
-  if (authorization && authorization.role.name) {
+  if (props.authorization && props.authorization.role.name) {
     // Debug: Log the values to check what's being used
-    const authParameter = `${authorization.role.name}: ${authorization.payload.name}`;
+    const authParameter = `${props.authorization.role.name}: ${props.authorization.payload.name}`;
     functionParameters.push(authParameter);
   }
 
   // Add path parameters (e.g., id, postId, etc.)
-  const pathParameters = operation.parameters.map((param) => {
-    const paramType = param.schema.type;
-    const paramFormat =
-      "format" in param.schema
-        ? ` & tags.Format<'${param.schema.format}'>`
-        : "";
-    return `${param.name}: ${paramType}${paramFormat}`;
+  const pathParameters = props.operation.parameters.map((param) => {
+    return `${param.name}: ${writeParameterType(param.schema)}`;
   });
   functionParameters.push(...pathParameters);
 
   // Add request body parameter if present
-  if (operation.requestBody?.typeName) {
-    const bodyParameter = `body: ${operation.requestBody.typeName}`;
+  if (props.operation.requestBody?.typeName) {
+    const bodyParameter = `body: ${props.operation.requestBody.typeName}`;
     functionParameters.push(bodyParameter);
   }
 
@@ -79,19 +75,55 @@ export function getRealizeWriteCodeTemplate(
   }
 
   // Determine return type
-  const returnType = operation.responseBody?.typeName ?? "void";
+  const returnType = props.operation.responseBody?.typeName ?? "void";
 
   // Generate the complete template
   return StringUtil.trim`
     Complete the code below, disregard the import part and return only the function part.
 
     \`\`\`typescript
-    ${getRealizeWriteImportStatements(operation).join("\n")} 
+    ${getRealizeWriteImportStatements(props).join("\n")} 
 
-    // ONLY YOU HAVE TO WRITE THIS, AND USE IMPORTED.
-    export async function ${scenario.functionName}(${formattedSignature}): Promise<${returnType}> {
+    // DON'T CHANGE FUNCTION NAME AND PARAMETERS,
+    // ONLY YOU HAVE TO WRITE THIS FUNCTION BODY, AND USE IMPORTED.
+    export async function ${props.scenario.functionName}(${formattedSignature}): Promise<${returnType}> {
       ...
     }
     \`\`\`
   `;
 }
+
+const writeParameterType = (
+  schema: AutoBeOpenApi.IParameter["schema"],
+): string => {
+  const elements: string[] =
+    schema.type === "integer"
+      ? ["number", `tags.Type<"int32">`]
+      : [schema.type];
+  if (schema.type === "number") {
+    if (schema.minimum !== undefined)
+      elements.push(`tags.Minimum<${schema.minimum}>`);
+    if (schema.maximum !== undefined)
+      elements.push(`tags.Maximum<${schema.maximum}>`);
+    if (schema.exclusiveMinimum !== undefined)
+      elements.push(`tags.ExclusiveMinimum<${schema.exclusiveMinimum}>`);
+    if (schema.exclusiveMaximum !== undefined)
+      elements.push(`tags.ExclusiveMaximum<${schema.exclusiveMaximum}>`);
+    if (schema.multipleOf !== undefined)
+      elements.push(`tags.MultipleOf<${schema.multipleOf}>`);
+  } else if (schema.type === "string") {
+    if (schema.format !== undefined)
+      elements.push(`tags.Format<${JSON.stringify(schema.format)}>`);
+    if (schema.contentMediaType !== undefined)
+      elements.push(
+        `tags.ContentMediaType<${JSON.stringify(schema.contentMediaType)}>`,
+      );
+    if (schema.pattern !== undefined)
+      elements.push(`tags.Pattern<${JSON.stringify(schema.pattern)}>`);
+    if (schema.minLength !== undefined)
+      elements.push(`tags.MinLength<${schema.minLength}>`);
+    if (schema.maxLength !== undefined)
+      elements.push(`tags.MaxLength<${schema.maxLength}>`);
+  }
+  return elements.join(" & ");
+};

package/src/orchestrate/realize/utils/getRealizeWriteImportStatements.ts

@@ -1,30 +1,42 @@
 import { AutoBeOpenApi } from "@autobe/interface";
+import { OpenApiTypeChecker } from "@samchon/openapi";
 
-export function getRealizeWriteImportStatements(
-  operation: AutoBeOpenApi.IOperation,
-) {
-  const typeReferences: string[] = Array.from(
-    new Set(
-      [operation.requestBody, operation.responseBody]
-        .filter((el) => el !== null)
-        .map((el) => el.typeName.split(".")[0]!),
-    ),
-  );
+export function getRealizeWriteImportStatements(props: {
+  operation: AutoBeOpenApi.IOperation;
+  schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+}): string[] {
+  const typeReferences: Set<string> = new Set();
+  const visit = (key: string) =>
+    OpenApiTypeChecker.visit({
+      schema: {
+        $ref: `#/components/schemas/${key}`,
+      },
+      components: { schemas: props.schemas },
+      closure: (next) => {
+        if (OpenApiTypeChecker.isReference(next))
+          typeReferences.add(next.$ref.split("/").pop()!.split(".")[0]!);
+      },
+    });
+  if (props.operation.requestBody) visit(props.operation.requestBody.typeName);
+  if (props.operation.responseBody)
+    visit(props.operation.responseBody.typeName);
 
   // Build the standard imports
   const imports = [
+    'import { HttpException } from "@nestjs/common";',
+    'import { Prisma } from "@prisma/client";',
     'import jwt from "jsonwebtoken";',
-    'import { MyGlobal } from "../MyGlobal";',
     'import typia, { tags } from "typia";',
-    'import { Prisma } from "@prisma/client";',
     'import { v4 } from "uuid";',
-    'import { toISOStringSafe } from "../util/toISOStringSafe"',
-    'import { HttpException } from "@nestjs/common";',
-    ...typeReferences.map(
+
+    'import { MyGlobal } from "../MyGlobal";',
+    'import { PasswordUtil } from "../utils/PasswordUtil";',
+    'import { toISOStringSafe } from "../utils/toISOStringSafe"',
+    "",
+    ...Array.from(typeReferences).map(
       (ref) =>
         `import { ${ref} } from "@ORGANIZATION/PROJECT-api/lib/structures/${ref}";`,
     ),
   ];
-
   return imports;
 }

package/src/orchestrate/realize/utils/printErrorHints.ts

@@ -0,0 +1,55 @@
+import { IAutoBeTypeScriptCompileResult } from "@autobe/interface";
+import { StringUtil } from "@autobe/utils";
+
+/**
+ * Prints error hints for a given code and its diagnostics.
+ *
+ * @param code The code to analyze.
+ * @param diagnostics The diagnostics to use for error hinting.
+ */
+export function printErrorHints(
+  code: string,
+  diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[],
+): string {
+  const lines: string[] = code.split("\n");
+
+  let cursor: number = 0;
+  const hints: string[] = [];
+  lines.forEach((line, index, arr) => {
+    const lineStart = cursor;
+    cursor += line.length + 1; // +1 for the newline character
+
+    diagnostics.forEach((diag) => {
+      if (diag.start === null || diag.start === undefined) {
+        return;
+      }
+
+      // Check if the diagnostic start position falls within the current line
+      if (diag.start >= lineStart && diag.start < cursor) {
+        // Handle multi-line error messages by escaping newlines
+        const errorMessage = String(diag.messageText).replace(/\n/g, "\\n");
+        const targetLine = line + " // error: " + errorMessage;
+
+        // targetLine만 덮어써서 새로운 배열을 만들어야 한다.
+        const hint: string = arr
+          .slice(0, index)
+          .concat(targetLine)
+          .concat(arr.slice(index + 1))
+          .join("\n");
+
+        hints.push(hint);
+      }
+    });
+  });
+
+  return hints
+    .map((h, i) => {
+      return StringUtil.trim`
+        hint #${i + 1}:
+        \`\`\`typescript
+        ${h}
+        \`\`\`
+      `;
+    })
+    .join("\n");
+}