@autobe/agent 0.13.0 → 0.14.2

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

@@ -36,18 +36,89 @@ export namespace IAutoBeRealizeCoderApplication {
     filename: string;
 
     /**
+     * Error Analysis Phase (Optional)
+     *
+     * 🔍 Analyzes TypeScript compilation errors from previous attempts.
+     *
+     * This field should contain a detailed analysis of any TypeScript errors
+     * encountered, with root cause identification and resolution strategies:
+     *
+     * Common Error Patterns to Analyze:
+     *
+     * 1. **"Property does not exist" (TS2353)**:
+     *
+     *    - Root Cause: Using fields that don't exist in Prisma schema
+     *    - Example: Using `deleted_at` when the field doesn't exist in the model
+     *    - Resolution: Remove the non-existent field or use hard delete instead
+     * 2. **"Type 'void' is not assignable" (TS2322)**:
+     *
+     *    - Root Cause: Using `typia.assertGuard` instead of `typia.assert`
+     *    - `assertGuard` returns void, `assert` returns the validated value
+     *    - Resolution: Change `typia.assertGuard<T>()` to `typia.assert<T>()`
+     * 3. **"Type 'Date' is not assignable to type 'string &
+     *    Format<'date-time'>'"**:
+     *
+     *    - Root Cause: Assigning native Date objects to string fields
+     *    - Resolution: Use `toISOStringSafe(dateValue)` for all date conversions
+     * 4. **Complex Prisma Type Errors**:
+     *
+     *    - Root Cause: Nested operations with incompatible types
+     *    - Resolution: Use separate queries and application-level joins
+     *
+     * Analysis Format:
+     *
+     * - List each error with its TypeScript error code
+     * - Identify the root cause (schema mismatch, wrong function usage, etc.)
+     * - Provide specific resolution steps
+     * - Note any schema limitations discovered
+     */
+    errorAnalysis?: string;
+
+    /**
+     * Step 1.
+     *
      * 🧠 Provider Function Implementation Plan
      *
      * This field outlines the strategic plan for implementing the provider
      * function according to the Realize Coder Agent specification. Before
      * writing the actual code, think through the logic and structure.
      *
-     * The plan must consider:
+     * The plan MUST follow MANDATORY SCHEMA-FIRST APPROACH:
+     *
+     * 📋 STEP 1 - PRISMA SCHEMA VERIFICATION (MOST CRITICAL):
+     *
+     * - EXAMINE the actual Prisma schema model definition
+     * - LIST EVERY field that exists in the model with exact types
+     * - EXPLICITLY NOTE fields that DO NOT exist (e.g., "Note: deleted_at field
+     *   DOES NOT EXIST")
+     * - Common assumption errors to avoid: `deleted_at`, `created_by`,
+     *   `updated_by`, `is_deleted`, `is_active`
+     *
+     * 📋 STEP 2 - FIELD INVENTORY:
+     *
+     * - List ONLY fields confirmed to exist in schema
+     * - Example: "Verified fields in user model: id (String), email (String),
+     *   created_at (DateTime), updated_at (DateTime)"
+     * - Example: "Fields that DO NOT exist: deleted_at, is_active, created_by"
+     *
+     * 📋 STEP 3 - FIELD ACCESS STRATEGY:
+     *
+     * - Plan which verified fields will be used in select, update, create
+     *   operations
+     * - For complex operations with type errors, plan to use separate queries
+     *   instead of nested operations
+     *
+     * 📋 STEP 4 - TYPE COMPATIBILITY:
+     *
+     * - Plan DateTime to ISO string conversions using toISOStringSafe()
+     * - Plan handling of nullable vs required fields
+     *
+     * 📋 STEP 5 - IMPLEMENTATION APPROACH:
      *
      * - 🧩 Required business entities (e.g., users, posts, logs) and their
      *   relationships
      * - 🛠 Operations needed to fulfill the business scenario (e.g., fetch,
-     *   create, update)
+     *   create, update) using ONLY verified fields
      * - 🔄 Data dependencies between steps (e.g., use userId to fetch related
      *   data)
      * - ✅ Validation points (based on business rules, not field presence)
@@ -69,7 +140,7 @@ export namespace IAutoBeRealizeCoderApplication {
      * ⚠️ TypeScript-specific considerations:
      *
      * - Do **not** use native `Date` objects directly; always convert all dates
-     *   to ISO strings with `.toISOString()` and brand as `string &
+     *   using `toISOStringSafe()` and brand as `string &
      *   tags.Format<'date-time'>`. This rule applies throughout all phases.
      * - Prefer `satisfies` for DTO conformance instead of unsafe `as` casts
      * - Avoid weak typing such as `any`, `as any`, or `satisfies any`
@@ -93,6 +164,18 @@ export namespace IAutoBeRealizeCoderApplication {
      * }
      * ```
      *
+     * 🔍 Feasibility Analysis Requirement:
+     *
+     * - Before generating any code, the agent **must analyze** whether the
+     *   requested implementation is **feasible based on the given Prisma schema
+     *   and DTO types**.
+     * - If required fields or relationships are **missing or incompatible**, the
+     *   plan should explicitly state that the implementation is **not
+     *   possible** with the current schema/DTO, and no code should be generated
+     *   in later stages.
+     * - In such cases, only a detailed **comment in the `implementationCode`**
+     *   should be returned explaining why the logic cannot be implemented.
+     *
      * 🔥 Error Handling Plan:
      *
      * If an error is expected or encountered during implementation:
@@ -118,10 +201,35 @@ export namespace IAutoBeRealizeCoderApplication {
     plan: string;
 
     /**
-     * ✏️ Phase 1: Draft code
+     * Step 2.
+     *
+     * The Prisma schema string that will be used to validate the implementation
+     * logic in this file.
+     *
+     * You must **explicitly specify only the relevant models and fields** from
+     * your full schema that are used in this implementation. This ensures that
+     * your logic is aligned with the expected database structure without
+     * accidentally introducing unrelated fields or models.
+     *
+     * ⚠️ Important: The value of this field must be a valid Prisma schema
+     * string containing only the models used in this code — not the entire
+     * schema.
+     *
+     * This acts as a safeguard against:
+     *
+     * - Forgetting required fields used in this implementation
+     * - Including fields or models that are not actually used
+     */
+    prisma_schemas: string;
+
+    /**
+     * Step 3.
+     *
+     * Draft WITHOUT using native Date type.
      *
      * This is the initial drafting phase where you outline the basic skeleton
-     * of the function.
+     * of the function. CRITICAL: This draft must NEVER use the native Date
+     * type.
      *
      * - The function signature must correctly include `user`, `parameters`, and
      *   `body` arguments.
@@ -141,14 +249,15 @@ export namespace IAutoBeRealizeCoderApplication {
      * ✅ Requirements:
      *
      * - Avoid using the `any` type at all costs to ensure type safety.
-     * - Do NOT assign native `Date` objects directly; always convert dates using
-     *   `.toISOString()` before assignment and apply proper branding.
+     * - NEVER declare variables with `: Date` type
+     * - ALWAYS use `string & tags.Format<'date-time'>` for date values
+     * - Use `toISOStringSafe(new Date())` for current timestamps
      * - Maintain a single-function structure; avoid using classes.
      */
     draft_without_date_type: string;
 
     /**
-     * 🔍 Phase 2: Review code
+     * Step 4.
      *
      * A refined version of the draft with improved completeness.
      *
@@ -160,13 +269,13 @@ export namespace IAutoBeRealizeCoderApplication {
      *
      * - Use `satisfies` to ensure DTO conformity.
      * - Avoid unsafe `as` casts unless only for branding or literal narrowing.
-     * - Include `.toISOString()` for all date fields.
+     * - Use `toISOStringSafe()` for all date conversions (NOT `.toISOString()`).
      * - Ensure all object keys strictly conform to the expected type definitions.
      */
     review: string;
 
     /**
-     * 🛠 Phase 3: With compiler feedback (optional)
+     * 🛠 Phase 4-2: With compiler feedback (optional)
      *
      * A correction pass that applies fixes for compile-time errors that arose
      * during the review stage (if any).
@@ -182,25 +291,45 @@ export namespace IAutoBeRealizeCoderApplication {
     withCompilerFeedback?: string;
 
     /**
-     * ✅ Phase 4: Final implementation
+     * Step 5.
      *
      * The complete and fully correct TypeScript function implementation.
      *
      * - Passes strict type checking without errors.
      * - Uses only safe branding or literal type assertions.
-     * - Converts all date values properly to ISO string format.
+     * - Converts all date values properly using `toISOStringSafe()`.
      * - Follows DTO structures using `satisfies`.
      * - Avoids any weak typing such as `any`, `as any`, or `satisfies any`.
-     * - Uses only allowed imports (e.g., from `src/api/structures` and
+     * - Uses only allowed imports (e.g., from `../api/structures` and
      *   `MyGlobal.prisma`).
+     * - NEVER creates intermediate variables for Prisma operations.
+     *
+     * ⚠️ Fallback Behavior:
+     *
+     * - If the `plan` phase explicitly determines that the requested logic is
+     *   **not feasible** due to mismatches or limitations in the provided
+     *   Prisma schema and DTO types:
+     *
+     *   - The implementation must still return a syntactically valid function.
+     *   - In such cases, return mock data using `typia.random<T>()` wrapped in the
+     *       correct structure, along with a comment explaining the limitation.
+     *
+     *   Example fallback:
+     *
+     * ```ts
+     *   // ⚠️ Cannot implement logic due to missing relation between A and B
+     *   export async function someFunction(...) {
+     *     return typia.random<IReturn>(); // mocked output
+     *   }
+     * ```
      *
      * ⚠️ Prohibited Practices:
      *
      * - Do NOT add or modify import statements manually. Imports are handled
      *   automatically by the system.
      * - Do NOT use `any`, `as any`, or `satisfies any` to bypass type checking.
-     * - Do NOT assign native `Date` objects directly; always convert them to ISO
-     *   strings with `.toISOString()`.
+     * - Do NOT assign native `Date` objects directly; always convert them using
+     *   `toISOStringSafe()`.
      * - Do NOT use unsafe type assertions except for safe branding or literal
      *   narrowing.
      * - Do NOT write code outside the single async function structure (e.g., no
@@ -209,8 +338,12 @@ export namespace IAutoBeRealizeCoderApplication {
      *   validated.
      * - Do NOT use dynamic import expressions (`import()`); all imports must be
      *   static.
-     * - Do NOT rely on DTO types for database update input; always use
-     *   Prisma-generated input types.
+     * - Do NOT use Prisma-generated input types; always use types from
+     *   `../api/structures`.
+     * - Do NOT use `Object.prototype.hasOwnProperty.call()` for field checks.
+     * - Do NOT escape newlines or quotes in the implementation string (e.g., no
+     *   `\\n` or `\"`); use a properly formatted template literal with actual
+     *   line breaks instead.
      */
     implementationCode: string;
   }

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

@@ -2,6 +2,7 @@ import {
   AutoBeOpenApi,
   IAutoBeTypeScriptCompileResult,
 } from "@autobe/interface";
+import { tags } from "typia";
 
 import { IAutoBeRealizeCoderApplication } from "./IAutoBeRealizeCoderApplication";
 import { FAILED } from "./IAutoBeRealizeFailedSymbol";
@@ -13,7 +14,10 @@ export namespace IAutoBeRealizeCompile {
     result: Pick<
       IAutoBeRealizeCoderApplication.RealizeCoderOutput,
       "filename" | "implementationCode"
-    >;
+    > & {
+      /** Function name */
+      name: string;
+    };
   }
 
   export interface Fail {
@@ -24,7 +28,14 @@ export namespace IAutoBeRealizeCompile {
 
   export type FileContentMap = Record<
     string,
-    { content: string; result: "failed" | "success" }
+    {
+      result: "failed" | "success";
+      content: string;
+      role?: (string & tags.MinLength<1>) | null;
+      endpoint?: AutoBeOpenApi.IEndpoint;
+      location?: string;
+      name?: string;
+    }
   >;
 
   export interface CompileDiagnostics {

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

@@ -21,13 +21,13 @@ export namespace IAutoBeRealizeDecoratorApplication {
     decorator: IAutoBeRealizeDecoratorApplication.IDecorator;
 
     /**
-     * Authentication Decorator Type configuration containing the decorator type
-     * name and implementation code. The Decorator Type is used to define the
+     * Authentication Payload Type configuration containing the payload type
+     * name and implementation code. The Payload Type is used to define the
      * structure of the authenticated user data that will be injected into
      * Controller methods when using the decorator. It serves as the TypeScript
      * type for the parameter in Controller method signatures.
      */
-    decoratorType: IAutoBeRealizeDecoratorApplication.IDecoratorType;
+    payload: IAutoBeRealizeDecoratorApplication.IPayloadType;
   }
 
   export interface IProvider {
@@ -72,7 +72,7 @@ export namespace IAutoBeRealizeDecoratorApplication {
     code: string;
   }
 
-  export interface IDecoratorType {
+  export interface IPayloadType {
     /**
      * The name of the Decorator to be generated in {Role}Auth format (e.g.,
      * AdminAuth, UserAuth). This decorator will be used as a parameter

package/src/orchestrate/realize/transformRealizeCoderHistories.ts

@@ -91,6 +91,25 @@ export const transformRealizeCoderHistories = (
       type: "systemMessage",
       text: AutoBeSystemPromptConstant.REALIZE_CODER_TOTAL,
     },
+    {
+      id: v4(),
+      created_at: new Date().toISOString(),
+      type: "systemMessage",
+      text: props.decoratorEvent
+        ? [
+            "Decorator-related files are already generated at the following locations:",
+            `- Decorator implementation: decorators/${props.decoratorEvent.decorator.name}.ts`,
+            `  - NestJS parameter decorator`,
+            `  - When importing from providers folder, use: '../decorators/${props.decoratorEvent.decorator.name}'`,
+            `- Authentication provider: authentications/${props.decoratorEvent.provider.name}.ts`,
+            `  - Contains JWT validation, role checking, and authorization logic`,
+            `  - When importing from providers folder, use: '../authentications/${props.decoratorEvent.provider.name}'`,
+            `- Type definition: authentications/types/${props.decoratorEvent.payload.name}.ts`,
+            `  - TypeScript interface for authenticated user payload`,
+            `  - When importing from providers folder, use: '../authentications/types/${props.decoratorEvent.payload.name}'`,
+          ].join("\n")
+        : "",
+    },
     {
       id: v4(),
       created_at: new Date().toISOString(),
@@ -116,19 +135,47 @@ export const transformRealizeCoderHistories = (
               // .replaceAll("{total_diagnostics}", JSON.stringify(total))
               .replaceAll("{current_diagnostics}", JSON.stringify(diagnostics)),
           } as const,
+          {
+            id: v4(),
+            created_at: new Date().toISOString(),
+            type: "systemMessage",
+            text: [
+              "Modify the previous code to reflect the following operation.",
+              "```json",
+              JSON.stringify(props),
+              "```",
+            ].join("\n"),
+          } as const,
         ]
-      : []),
+      : [
+          {
+            id: v4(),
+            created_at: new Date().toISOString(),
+            type: "systemMessage",
+            text: [
+              "Write new code based on the following operation.",
+              "```json",
+              JSON.stringify(props),
+              "```",
+            ].join("\n"),
+          } as const,
+        ]),
     {
       id: v4(),
       created_at: new Date().toISOString(),
-      type: "systemMessage",
+      type: "assistantMessage",
       text: [
-        previous
-          ? "Modify the previous code to reflect the following operation."
-          : "Write new code based on the following operation.",
-        "```json",
-        JSON.stringify(props),
-        "```",
+        `I understand your request.`,
+        ``,
+        `To summarize:`,
+        `- I must **never use the native \`Date\` type** in any code or type definitions.`,
+        `- Instead, all date and datetime values must be handled as \`string & tags.Format<'date-time'>\`.`,
+        `- This rule is **strict** and applies everywhere, including domain types, API inputs/outputs, and Prisma models.`,
+        `- Even if a library or tool returns a \`Date\`, I must convert it to the correct string format before use.`,
+        ``,
+        `Especially regarding the \`Date\` type: I understand that using it can lead to type inconsistency and runtime issues, so I will completely avoid it in all circumstances.`,
+        ``,
+        `I'll make sure to follow all these rules strictly. Let’s proceed with this in mind.`,
       ].join("\n"),
     },
     {

package/src/orchestrate/realize/transformRealizeDecoratorCorrectHistories.ts

@@ -1,5 +1,8 @@
 import { IAgenticaHistoryJson } from "@agentica/core";
-import { IAutoBeTypeScriptCompileResult } from "@autobe/interface";
+import {
+  AutoBeRealizeAuthorization,
+  IAutoBeTypeScriptCompileResult,
+} from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 import { v4 } from "uuid";
 
@@ -9,7 +12,7 @@ import { IAutoBeRealizeDecoratorApplication } from "./structures/IAutoBeRealizeD
 
 export const transformRealizeDecoratorCorrectHistories = (
   ctx: AutoBeContext<ILlmSchema.Model>,
-  result: IAutoBeRealizeDecoratorApplication.IProps,
+  auth: AutoBeRealizeAuthorization,
   templateFiles: Record<string, string>,
   diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[],
 ): Array<
@@ -30,7 +33,24 @@ export const transformRealizeDecoratorCorrectHistories = (
         "## Generated TypeScript Code",
         "",
         "```json",
-        `${JSON.stringify(result, null, 2)}`,
+        `${JSON.stringify(
+          {
+            provider: {
+              name: auth.provider.name,
+              code: auth.provider.content,
+            },
+            decorator: {
+              name: auth.decorator.name,
+              code: auth.decorator.content,
+            },
+            payload: {
+              name: auth.payload.name,
+              code: auth.payload.content,
+            },
+          } satisfies IAutoBeRealizeDecoratorApplication.IProps,
+          null,
+          2,
+        )}`,
         "```",
         "",
         "## Prisma Schema",

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

@@ -0,0 +1,10 @@
+export namespace AuthorizationFileSystem {
+  export const decoratorPath = (name: string): string =>
+    `src/decorators/${name}.ts`;
+
+  export const payloadPath = (name: string): string =>
+    `src/decorators/payload/${name}.ts`;
+
+  export const providerPath = (name: string): string =>
+    `src/providers/authorize/${name}.ts`;
+}

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

@@ -0,0 +1,85 @@
+import { IAutoBeCompiler } from "@autobe/interface";
+import { ILlmSchema } from "@samchon/openapi";
+
+import { AutoBeContext } from "../../../context/AutoBeContext";
+
+export function replaceImportStatements<Model extends ILlmSchema.Model>(
+  ctx: AutoBeContext<Model>,
+) {
+  return async function (code: string, decoratorType?: string) {
+    const compiler: IAutoBeCompiler = await ctx.compiler();
+    code = await compiler.typescript.beautify(code);
+    // Remove existing import statements using flexible regex patterns
+    code = code
+      .replace(
+        /import\s*{\s*MyGlobal\s*}\s*from\s*["']\.\.\/MyGlobal["']\s*;?\s*/gm,
+        "",
+      )
+      .replace(
+        /import\s+typia\s*,\s*{\s*tags\s*}\s*from\s*["']typia["']\s*;?\s*/gm,
+        "",
+      )
+      .replace(/import\s*{\s*tags\s*}\s*from\s*["']typia["']\s*;?\s*/gm, "")
+      .replace(
+        /import\s*{\s*tags\s*,\s*typia\s*}\s*from\s*["']typia["']\s*;?\s*/gm,
+        "",
+      )
+      .replace(/import\s+typia\s*from\s*["']typia["']\s*;?\s*/gm, "")
+      .replace(
+        /import\s*{\s*Prisma\s*}\s*from\s*["']@prisma\/client["']\s*;?\s*/gm,
+        "",
+      )
+      .replace(/import\s*{\s*v4\s*}\s*from\s*["']uuid["']\s*;?\s*/gm, "")
+      .replace(
+        /import\s*{\s*toISOStringSafe\s*}\s*from\s*["']\.\.\/util\/toISOStringSafe["']\s*;?\s*/gm,
+        "",
+      );
+
+    // Remove any existing decoratorType imports if LLM mistakenly added them
+    if (decoratorType) {
+      const decoratorTypeRegex = new RegExp(
+        `import\\s*{\\s*${decoratorType}\\s*}\\s*from\\s*["']\\.\\.\/authentications\/types\/${decoratorType}["']\\s*;?\\s*`,
+        "gm",
+      );
+      code = code.replace(decoratorTypeRegex, "");
+    }
+
+    // Build the standard imports
+    const imports = [
+      'import { MyGlobal } from "../MyGlobal";',
+      'import typia, { tags } from "typia";',
+      'import { Prisma } from "@prisma/client";',
+      'import { v4 } from "uuid";',
+      'import { toISOStringSafe } from "../util/toISOStringSafe"',
+    ];
+
+    // Only add decoratorType import if it exists
+    if (decoratorType) {
+      imports.push(
+        `import { ${decoratorType} } from "../authentications/types/${decoratorType}"`,
+      );
+    }
+
+    code = [...imports, "", code].join("\n");
+
+    // Clean up formatting issues
+    code =
+      code
+        // Remove lines with only whitespace
+        .replace(/^\s+$/gm, "")
+        // Replace 3+ consecutive newlines with exactly 2 newlines
+        .replace(/\n{3,}/g, "\n\n")
+        // Ensure proper spacing after import section
+        .replace(/(import.*?;)(\s*)(\n(?!import|\s*$))/g, "$1\n\n$3")
+        // Trim and ensure single trailing newline
+        .trim() + "\n";
+
+    // fix escaped codes
+    code = code.replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\'/g, "'");
+
+    // Apply final beautification
+    code = await compiler.typescript.beautify(code);
+
+    return code;
+  };
+}