@autobe/agent 0.18.0 → 0.19.1

package/src/orchestrate/interface/orchestrateInterfaceOperationsReview.ts

@@ -2,13 +2,13 @@ import { IAgenticaController } from "@agentica/core";
 import {
   AutoBeInterfaceOperationsReviewEvent,
   AutoBeOpenApi,
+  AutoBeProgressEventBase,
 } from "@autobe/interface";
 import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
 import { IPointer } from "tstl";
 import typia from "typia";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
-import { IProgress } from "../internal/IProgress";
 import { transformInterfaceOperationsReviewHistories } from "./histories/transformInterfaceOperationsReviewHistories";
 import { IAutoBeInterfaceOperationsReviewApplication } from "./structures/IAutoBeInterfaceOperationsReviewApplication";
 
@@ -17,39 +17,56 @@ export async function orchestrateInterfaceOperationsReview<
 >(
   ctx: AutoBeContext<Model>,
   operations: AutoBeOpenApi.IOperation[],
-  progress: IProgress,
+  progress: AutoBeProgressEventBase,
 ): Promise<AutoBeOpenApi.IOperation[]> {
-  const pointer: IPointer<IAutoBeInterfaceOperationsReviewApplication.IProps | null> =
-    {
-      value: null,
-    };
-  const { tokenUsage } = await ctx.conversate({
-    source: "interfaceOperationsReview",
-    histories: transformInterfaceOperationsReviewHistories(ctx, operations),
-    controller: createReviewController({
-      model: ctx.model,
-      build: (next: IAutoBeInterfaceOperationsReviewApplication.IProps) => {
-        pointer.value = next;
-      },
-    }),
-    enforceFunctionCall: false,
-    message: "Review the operations",
-  });
-  if (pointer.value === null) throw new Error("Failed to review operations.");
+  try {
+    const pointer: IPointer<IAutoBeInterfaceOperationsReviewApplication.IProps | null> =
+      {
+        value: null,
+      };
+    const { tokenUsage } = await ctx.conversate({
+      source: "interfaceOperationsReview",
+      histories: transformInterfaceOperationsReviewHistories(ctx, operations),
+      controller: createReviewController({
+        model: ctx.model,
+        build: (next: IAutoBeInterfaceOperationsReviewApplication.IProps) => {
+          pointer.value = next;
+        },
+      }),
+      enforceFunctionCall: false,
+      message: "Review the operations",
+    });
+    if (pointer.value === null) {
+      console.error("Failed to review operations.");
+      progress.completed += operations.length;
+      return [];
+    }
+
+    const content: AutoBeOpenApi.IOperation[] = pointer.value.content.map(
+      (op) => ({
+        ...op,
+        authorizationType: null,
+      }),
+    );
 
-  ctx.dispatch({
-    type: "interfaceOperationsReview",
-    operations: pointer.value.content,
-    review: pointer.value.review,
-    plan: pointer.value.plan,
-    content: pointer.value.content,
-    tokenUsage,
-    created_at: new Date().toISOString(),
-    step: ctx.state().analyze?.step ?? 0,
-    total: progress.total,
-    completed: ++progress.completed,
-  } satisfies AutoBeInterfaceOperationsReviewEvent);
-  return pointer.value.content;
+    ctx.dispatch({
+      type: "interfaceOperationsReview",
+      operations: content,
+      review: pointer.value.review,
+      plan: pointer.value.plan,
+      content,
+      tokenUsage,
+      created_at: new Date().toISOString(),
+      step: ctx.state().analyze?.step ?? 0,
+      total: progress.total,
+      completed: ++progress.completed,
+    } satisfies AutoBeInterfaceOperationsReviewEvent);
+    return content;
+  } catch (error) {
+    console.error("Error occurred during interface operations review:", error);
+    ++progress.completed;
+    return [];
+  }
 }
 
 function createReviewController<Model extends ILlmSchema.Model>(props: {

package/src/orchestrate/interface/orchestrateInterfaceSchemas.ts

@@ -1,24 +1,28 @@
 import { IAgenticaController } from "@agentica/core";
-import { AutoBeInterfaceSchemasEvent, AutoBeOpenApi } from "@autobe/interface";
-import { ILlmApplication, ILlmSchema } from "@samchon/openapi";
+import {
+  AutoBeInterfaceSchemasEvent,
+  AutoBeOpenApi,
+  AutoBeProgressEventBase,
+} from "@autobe/interface";
+import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
 import { OpenApiV3_1Emender } from "@samchon/openapi/lib/converters/OpenApiV3_1Emender";
 import { IPointer } from "tstl";
-import typia from "typia";
+import typia, { tags } from "typia";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
 import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { divideArray } from "../../utils/divideArray";
-import { IProgress } from "../internal/IProgress";
 import { transformInterfaceSchemaHistories } from "./histories/transformInterfaceSchemaHistories";
 import { orchestrateInterfaceSchemasReview } from "./orchestrateInterfaceSchemasReview";
 import { IAutoBeInterfaceSchemaApplication } from "./structures/IAutoBeInterfaceSchemaApplication";
+import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemas<
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
   operations: AutoBeOpenApi.IOperation[],
-  capacity: number = 12,
+  capacity: number = 8,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   const typeNames: Set<string> = new Set();
   for (const op of operations) {
@@ -29,29 +33,40 @@ export async function orchestrateInterfaceSchemas<
     array: Array.from(typeNames),
     capacity,
   });
-  const progress: IProgress = {
+  const progress: AutoBeProgressEventBase = {
     total: typeNames.size,
     completed: 0,
   };
-  const reviewProgress: IProgress = {
+  const reviewProgress: AutoBeProgressEventBase = {
     total: matrix.length,
     completed: 0,
   };
-  const x: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+  const roles: string[] =
+    ctx.state().analyze?.roles.map((role) => role.name) ?? [];
+
+  const x: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+    roles.length > 0
+      ? {
+          IAuthorizationToken: authTokenSchema,
+        }
+      : {};
   for (const y of await Promise.all(
     matrix.map(async (it) => {
       const row: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
         await divideAndConquer(ctx, operations, it, 3, progress);
-      return orchestrateInterfaceSchemasReview(
-        ctx,
-        operations,
-        row,
-        reviewProgress,
-      );
+      const newbie: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+        await orchestrateInterfaceSchemasReview(
+          ctx,
+          operations,
+          row,
+          reviewProgress,
+        );
+      return { ...row, ...newbie };
     }),
   )) {
     Object.assign(x, y);
   }
+  if (x.IAuthorizationToken) x.IAuthorizationToken = authTokenSchema;
   return x;
 }
 
@@ -60,7 +75,7 @@ async function divideAndConquer<Model extends ILlmSchema.Model>(
   operations: AutoBeOpenApi.IOperation[],
   typeNames: string[],
   retry: number,
-  progress: IProgress,
+  progress: AutoBeProgressEventBase,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   const remained: Set<string> = new Set(typeNames);
   const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
@@ -81,7 +96,7 @@ async function process<Model extends ILlmSchema.Model>(
   operations: AutoBeOpenApi.IOperation[],
   oldbie: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
   remained: Set<string>,
-  progress: IProgress,
+  progress: AutoBeProgressEventBase,
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
   const already: string[] = Object.keys(oldbie);
   const pointer: IPointer<Record<
@@ -134,10 +149,10 @@ async function process<Model extends ILlmSchema.Model>(
     type: "interfaceSchemas",
     schemas,
     tokenUsage,
-    completed: (progress.completed += Object.keys(schemas).filter(
-      (k) => oldbie[k] === undefined,
+    completed: (progress.completed += Object.keys(schemas).length),
+    total: (progress.total += Object.keys(schemas).filter(
+      (k) => remained.has(k) === false,
     ).length),
-    total: progress.total,
     step: ctx.state().prisma?.step ?? 0,
     created_at: new Date().toISOString(),
   } satisfies AutoBeInterfaceSchemasEvent);
@@ -156,9 +171,34 @@ function createController<Model extends ILlmSchema.Model>(props: {
 }): IAgenticaController.IClass<Model> {
   assertSchemaModel(props.model);
 
+  const validate = (
+    next: unknown,
+  ): IValidation<IAutoBeInterfaceSchemaApplication.IProps> => {
+    const result: IValidation<IAutoBeInterfaceSchemaApplication.IProps> =
+      typia.validate<IAutoBeInterfaceSchemaApplication.IProps>(next);
+    if (result.success === false) return result;
+
+    // Check all IAuthorized types
+    const errors: IValidation.IError[] = [];
+    validateAuthorizationSchema({
+      errors,
+      schemas: result.data.schemas,
+      path: "$input.schemas",
+    });
+    if (errors.length !== 0)
+      return {
+        success: false,
+        errors,
+        data: next,
+      };
+    return result;
+  };
+
   const application: ILlmApplication<Model> = collection[
-    props.model
-  ] satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
+    props.model === "chatgpt" ? "chatgpt" : "claude"
+  ](
+    validate,
+  ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
   return {
     protocol: "class",
     name: "interface",
@@ -171,17 +211,71 @@ function createController<Model extends ILlmSchema.Model>(props: {
   };
 }
 
-const claude = typia.llm.application<
-  IAutoBeInterfaceSchemaApplication,
-  "claude"
->();
 const collection = {
-  chatgpt: typia.llm.application<
-    IAutoBeInterfaceSchemaApplication,
-    "chatgpt"
-  >(),
-  claude,
-  llama: claude,
-  deepseek: claude,
-  "3.1": claude,
+  chatgpt: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemaApplication, "chatgpt">({
+      validate: {
+        makeComponents: validate,
+      },
+    }),
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemaApplication, "claude">({
+      validate: {
+        makeComponents: validate,
+      },
+    }),
 };
+
+type Validator = (
+  input: unknown,
+) => IValidation<IAutoBeInterfaceSchemaApplication.IProps>;
+
+/**
+ * Authorization token response structure.
+ *
+ * This interface defines the structure of the authorization token response
+ * returned after successful user authentication. It contains both access and
+ * refresh tokens along with their expiration information.
+ *
+ * This token structure is automatically included in API schemas when the system
+ * detects authorization roles in the requirements analysis phase. It provides a
+ * standard format for JWT-based authentication across the generated backend
+ * applications.
+ */
+interface IAuthorizationToken {
+  /**
+   * JWT access token for authenticated requests.
+   *
+   * This token should be included in the Authorization header for subsequent
+   * authenticated API requests as `Bearer {token}`.
+   */
+  access: string;
+
+  /**
+   * Refresh token for obtaining new access tokens.
+   *
+   * This token can be used to request new access tokens when the current access
+   * token expires, extending the user's session.
+   */
+  refresh: string;
+
+  /**
+   * Access token expiration timestamp.
+   *
+   * ISO 8601 date-time string indicating when the access token will expire and
+   * can no longer be used for authentication.
+   */
+  expired_at: string & tags.Format<"date-time">;
+
+  /**
+   * Refresh token expiration timestamp.
+   *
+   * ISO 8601 date-time string indicating the latest time until which the
+   * refresh token can be used to obtain new access tokens.
+   */
+  refreshable_until: string & tags.Format<"date-time">;
+}
+
+const authTokenSchema: AutoBeOpenApi.IJsonSchemaDescriptive =
+  typia.json.schema<IAuthorizationToken>().components.schemas!
+    .IAuthorizationToken as AutoBeOpenApi.IJsonSchemaDescriptive;

package/src/orchestrate/interface/orchestrateInterfaceSchemasReview.ts

@@ -4,12 +4,15 @@ import {
   AutoBeOpenApi,
 } from "@autobe/interface";
 import { ILlmApplication, ILlmSchema, IValidation } from "@samchon/openapi";
+import { OpenApiV3_1Emender } from "@samchon/openapi/lib/converters/OpenApiV3_1Emender";
 import { IPointer } from "tstl";
 import typia from "typia";
 
 import { AutoBeContext } from "../../context/AutoBeContext";
+import { assertSchemaModel } from "../../context/assertSchemaModel";
 import { transformInterfaceSchemasReviewHistories } from "./histories/transformInterfaceSchemasReviewHistories";
 import { IAutoBeInterfaceSchemasReviewApplication } from "./structures/IAutobeInterfaceSchemasReviewApplication";
+import { validateAuthorizationSchema } from "./utils/validateAuthorizationSchema";
 
 export async function orchestrateInterfaceSchemasReview<
   Model extends ILlmSchema.Model,
@@ -22,42 +25,56 @@ export async function orchestrateInterfaceSchemasReview<
   >,
   progress: { total: number; completed: number },
 ): Promise<Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>> {
-  const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
-    {
-      value: null,
-    };
-
-  const { tokenUsage } = await ctx.conversate({
-    source: "interfaceSchemasReview",
-    controller: createController({
-      model: ctx.model,
-      pointer,
-      schemas,
-    }),
-    histories: transformInterfaceSchemasReviewHistories(
-      ctx.state(),
-      operations,
-      schemas,
-    ),
-    enforceFunctionCall: true,
-    message: "Review type schemas.",
-  });
-  if (pointer.value === null)
-    throw new Error("Failed to extract review information.");
+  try {
+    const pointer: IPointer<IAutoBeInterfaceSchemasReviewApplication.IProps | null> =
+      {
+        value: null,
+      };
+    const { tokenUsage } = await ctx.conversate({
+      source: "interfaceSchemasReview",
+      controller: createController({
+        model: ctx.model,
+        pointer,
+        schemas,
+      }),
+      histories: transformInterfaceSchemasReviewHistories(
+        ctx.state(),
+        operations,
+        schemas,
+      ),
+      enforceFunctionCall: true,
+      message: "Review type schemas.",
+    });
+    if (pointer.value === null) {
+      console.error("Failed to extract review information.");
+      ++progress.completed;
+      return {};
+    }
 
-  ctx.dispatch({
-    type: "interfaceSchemasReview",
-    schemas: schemas,
-    review: pointer.value.review,
-    plan: pointer.value.plan,
-    content: pointer.value.content,
-    tokenUsage,
-    step: ctx.state().analyze?.step ?? 0,
-    total: progress.total,
-    completed: ++progress.completed,
-    created_at: new Date().toISOString(),
-  } satisfies AutoBeInterfaceSchemasReviewEvent);
-  return pointer.value.content;
+    const content: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+      (
+        OpenApiV3_1Emender.convertComponents({
+          schemas: pointer.value.content,
+        }) as AutoBeOpenApi.IComponents
+      ).schemas ?? {};
+    ctx.dispatch({
+      type: "interfaceSchemasReview",
+      schemas: schemas,
+      review: pointer.value.review,
+      plan: pointer.value.plan,
+      content,
+      tokenUsage,
+      step: ctx.state().analyze?.step ?? 0,
+      total: progress.total,
+      completed: ++progress.completed,
+      created_at: new Date().toISOString(),
+    } satisfies AutoBeInterfaceSchemasReviewEvent);
+    return content;
+  } catch (error) {
+    console.error("Error occurred during interface schemas review:", error);
+    ++progress.completed;
+    return {};
+  }
 }
 
 function createController<Model extends ILlmSchema.Model>(props: {
@@ -68,6 +85,8 @@ function createController<Model extends ILlmSchema.Model>(props: {
     AutoBeOpenApi.IJsonSchemaDescriptive<AutoBeOpenApi.IJsonSchema>
   >;
 }): IAgenticaController.IClass<Model> {
+  assertSchemaModel(props.model);
+
   const validate = (
     next: unknown,
   ): IValidation<IAutoBeInterfaceSchemasReviewApplication.IProps> => {
@@ -76,37 +95,24 @@ function createController<Model extends ILlmSchema.Model>(props: {
     if (result.success === false) return result;
 
     const errors: IValidation.IError[] = [];
-    if (Object.keys(result.data.content).length === 0) {
-      console.log();
-      console.log();
-      console.log();
-      console.log(
-        JSON.stringify({ schemas: props.schemas, ...result.data }, null, 2),
-      );
-      errors.push({
-        path: `$input.content`,
-        expected: `Content must not be empty. If it's at a level that can't be fixed, please create a schema instead to meet the requirements.`,
-        value: result.data.content,
-      });
-    }
-
-    if (errors.length > 0) {
+    validateAuthorizationSchema({
+      errors,
+      schemas: result.data.content,
+      path: "$input.content",
+    });
+    if (errors.length !== 0)
       return {
         success: false,
         errors,
-        data: result.data,
+        data: next,
       };
-    }
-
     return result;
   };
-
   const application: ILlmApplication<Model> = collection[
     props.model === "chatgpt" ? "chatgpt" : "claude"
   ](
     validate,
   ) satisfies ILlmApplication<any> as unknown as ILlmApplication<Model>;
-
   return {
     protocol: "class",
     name: "Reviewer",
@@ -118,12 +124,6 @@ function createController<Model extends ILlmSchema.Model>(props: {
     } satisfies IAutoBeInterfaceSchemasReviewApplication,
   };
 }
-const claude = (validate: Validator) =>
-  typia.llm.application<IAutoBeInterfaceSchemasReviewApplication, "claude">({
-    validate: {
-      review: validate,
-    },
-  });
 
 const collection = {
   chatgpt: (validate: Validator) =>
@@ -132,10 +132,12 @@ const collection = {
         review: validate,
       },
     }),
-  claude,
-  llama: claude,
-  deepseek: claude,
-  "3.1": claude,
+  claude: (validate: Validator) =>
+    typia.llm.application<IAutoBeInterfaceSchemasReviewApplication, "claude">({
+      validate: {
+        review: validate,
+      },
+    }),
 };
 
 type Validator = (

package/src/orchestrate/interface/structures/IAutoBeInterfaceComplementApplication.ts

@@ -20,6 +20,45 @@ export interface IAutoBeInterfaceComplementApplication {
 }
 export namespace IAutoBeInterfaceComplementApplication {
   export interface IProps {
+    /**
+     * TypeScript draft code for complement schema definitions.
+     *
+     * This property contains TypeScript interface definitions for missing schema
+     * types that were referenced but not defined in the initial schema generation.
+     * Similar to the main schema draft, this serves as a preliminary TypeScript
+     * representation before converting to JSON Schema format.
+     *
+     * The draft helps ensure that complementary schemas maintain consistency with
+     * the existing type system and follow the same conventions as the primary schemas.
+     * 
+     * This draft typically includes:
+     * - Missing entity interfaces referenced via $ref
+     * - Nested object types used within other schemas
+     * - Shared utility types or enumerations
+     * - Any transitively referenced types
+     *
+     * The final schemas in the `schemas` property should be validated against and
+     * derived from this TypeScript draft to ensure type safety and consistency
+     * across the entire API specification.
+     *
+     * Example complement draft:
+     * ```typescript
+     * interface IUserProfile {
+     *   id: string;
+     *   userId: string;
+     *   displayName: string;
+     *   avatarUrl?: string;
+     * }
+     * 
+     * interface IAddress {
+     *   street: string;
+     *   city: string;
+     *   postalCode: string;
+     * }
+     * ```
+     */
+    draft: string;
+
     /**
      * A collection of missing schema definitions that need to be added to the
      * OpenAPI document's `components.schemas` section.

package/src/orchestrate/interface/structures/IAutoBeInterfaceGroupApplication.ts

@@ -5,10 +5,10 @@ export interface IAutoBeInterfaceGroupApplication {
    * Generate logical groups for organizing API endpoint creation based on
    * Prisma schema structure.
    *
-   * Groups MUST be derived from Prisma schema organization (namespaces, file
-   * structure, table prefixes) rather than arbitrary business domains. Only
-   * create new groups when existing schema structure cannot adequately cover
-   * all requirements.
+   * DO: Derive groups from Prisma schema organization (namespaces, file
+   * structure, table prefixes) rather than arbitrary business domains.
+   * DO: Create new groups only when existing schema structure cannot adequately
+   * cover all requirements.
    *
    * @param props Properties containing the groups to be created for API
    *   organization
@@ -21,8 +21,8 @@ export namespace IAutoBeInterfaceGroupApplication {
     /**
      * Array of API endpoint groups for organizing development.
      *
-     * Groups MUST be organized around existing Prisma schema structure and
-     * provide complete coverage of all entities and requirements without
+     * DO: Organize groups around existing Prisma schema structure.
+     * DO: Provide complete coverage of all entities and requirements without
      * overlap.
      */
     groups: IGroup[] & tags.MinItems<1>;
@@ -34,10 +34,11 @@ export namespace IAutoBeInterfaceGroupApplication {
    *
    * **SCHEMA-BASED GROUP REQUIREMENTS:**
    *
-   * Groups MUST be derived from the Prisma schema structure rather than
-   * arbitrary business domain names. This ensures consistency with the
-   * underlying data model and prevents misalignment between API organization
-   * and database structure.
+   * DO: Derive groups from the Prisma schema structure rather than arbitrary
+   * business domain names.
+   * 
+   * This ensures consistency with the underlying data model and prevents
+   * misalignment between API organization and database structure.
    *
    * **Primary Group Sources (in order of priority):**
    *
@@ -51,12 +52,11 @@ export namespace IAutoBeInterfaceGroupApplication {
    *
    * **Group Creation Guidelines:**
    *
-   * - Each group must cover specific Prisma schema entities without overlap
+   * - Each group covers specific Prisma schema entities without overlap
    * - Size groups appropriately for manageable endpoint generation cycles
    * - Maintain clear boundaries based on schema organization
    * - Ensure complete coverage of all database entities and requirements
-   * - Related database tables within the same schema area should be grouped
-   *   together
+   * - Related database tables within the same schema area are grouped together
    *
    * **When to Create Schema-Independent Groups:**
    *
@@ -71,14 +71,14 @@ export namespace IAutoBeInterfaceGroupApplication {
    * **Naming Standards:**
    *
    * - Use PascalCase format (e.g., "Shopping", "BBS", "UserManagement")
-   * - Names MUST directly reflect Prisma schema structure
+   * - Names directly reflect Prisma schema structure
    * - Keep names concise and schema-derived
    * - Avoid arbitrary business domain names
    * - Maintain consistency with schema organization
    *
    * **Quality Requirements:**
    *
-   * - Groups collectively must cover ALL entities and requirements
+   * - Groups collectively cover ALL entities and requirements
    * - Each database entity belongs to exactly one group
    * - Clear mapping to specific Prisma schema elements
    * - Balance group sizes within schema constraints
@@ -88,7 +88,7 @@ export namespace IAutoBeInterfaceGroupApplication {
     /**
      * Unique identifier name derived from Prisma schema structure.
      *
-     * Must correspond to schema namespaces, file names, table prefixes, or
+     * DO: Correspond to schema namespaces, file names, table prefixes, or
      * organizational annotations rather than arbitrary business domain names.
      */
     name: string & tags.MinLength<1>;