@autobe/agent 0.30.4 → 0.30.5

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

@@ -10,10 +10,6 @@ export interface IAutoBeInterfaceOperationApplication {
   /**
    * Process operation generation task or preliminary data requests.
    *
-   * Creates a complete API operation following REST principles and quality
-   * standards. Processes the operation with progress tracking to ensure
-   * iterative completion.
-   *
    * @param props Request containing either preliminary data request or complete
    *   task
    */
@@ -24,34 +20,16 @@ export namespace IAutoBeInterfaceOperationApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests (getAnalysisSections, getDatabaseSchemas, etc.):
-     *
-     * - What critical information is missing that you don't already have?
-     * - Why do you need it specifically right now?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion (complete):
+     * For preliminary requests: what critical information is missing and why?
+     * Be brief — state the gap, don't list everything you have.
      *
-     * - What key assets did you acquire?
-     * - What did you accomplish?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every single item.
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * For completion: what key assets did you acquire, what did you accomplish,
+     * why is it sufficient? Summarize — don't enumerate every single item.
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval
-     * (getAnalysisSections, getDatabaseSchemas, getPreviousAnalysisSections,
-     * getPreviousDatabaseSchemas) or final operation generation (complete).
-     * When preliminary returns empty array, that type is removed from the
+     * Action to perform. Exhausted preliminary types are removed from the
      * union, physically preventing repeated calls.
      */
     request:
@@ -63,113 +41,40 @@ export namespace IAutoBeInterfaceOperationApplication {
       | IAutoBePreliminaryGetPreviousInterfaceOperations;
   }
 
-  /**
-   * Request to generate a detailed API operation.
-   *
-   * Executes operation generation to create a complete API operation following
-   * REST principles and quality standards. The operation includes
-   * specification, path, method, detailed description, summary, parameters, and
-   * request/response bodies.
-   */
+  /** Request to generate a detailed API operation. */
   export interface IComplete {
-    /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval or actual
-     * task execution. Value "complete" indicates this is the final task
-     * execution request.
-     */
+    /** Type discriminator for completion request. */
     type: "complete";
 
-    /**
-     * Analysis of the endpoint's purpose and context.
-     *
-     * Before designing the operation, analyze what you know:
-     *
-     * - What is this endpoint for? What business requirement does it fulfill?
-     * - What database entities and fields are involved?
-     * - What parameters, request body, and response are needed?
-     * - What authorization actors should have access?
-     */
+    /** Analysis of the endpoint's purpose and context. */
     analysis: string;
 
-    /**
-     * Rationale for the operation design decisions.
-     *
-     * Explain why you designed the operation this way:
-     *
-     * - Why did you choose these parameters and body types?
-     * - What authorization actors did you select and why?
-     * - How does this operation fulfill the endpoint description?
-     * - What was excluded from the design and why?
-     */
+    /** Rationale for the operation design decisions. */
     rationale: string;
 
     /**
      * The API operation to generate.
      *
-     * The operation includes:
+     * Follow CRUD operation patterns:
      *
-     * - Specification: Detailed API specification with clear purpose and
-     *   functionality
-     * - Path: Resource-centric URL path (e.g., "/resources/{resourceId}")
-     * - Method: HTTP method (get, post, put, delete, patch)
-     * - Description: Extremely detailed multi-paragraph description referencing
-     *   database schema comments
-     * - Summary: Concise one-sentence summary of the endpoint
-     * - Parameters: Array of all necessary parameters with descriptions and
-     *   schema definitions
-     * - RequestBody: For POST/PUT/PATCH methods, with typeName referencing
-     *   components.schemas
-     * - ResponseBody: With typeName referencing appropriate response type
+     * - List/search (PATCH `index`): include pagination, search, and sorting in
+     *   request body
+     * - Detail retrieval (GET `at`): return single full entity
+     * - Creation (POST): use `.ICreate` request body
+     * - Modification (PUT): use `.IUpdate` request body
      *
-     * The operation follows strict quality standards:
-     *
-     * 1. Detailed descriptions referencing database schema comments
-     * 2. Accurate parameter definitions matching path parameters
-     * 3. Appropriate request/response body type references
-     * 4. Consistent patterns for CRUD operations
-     *
-     * For list retrievals (typically PATCH), include pagination, search, and
-     * sorting. For detail retrieval (GET), return a single resource. For
-     * creation (POST), use .ICreate request body. For modification (PUT), use
-     * .IUpdate request body.
+     * Use object types for request/response bodies, reference named component
+     * types, and `application/json` content-type.
      */
     operation: IOperation;
   }
 
   /**
-   * Operation of the Restful API.
-   *
-   * This interface defines a single API endpoint with its HTTP {@link method},
-   * {@link path}, {@link parameters path parameters},
-   * {@link requestBody request body}, and {@link responseBody} structure. It
-   * corresponds to an individual operation in the paths section of an OpenAPI
-   * document.
-   *
-   * Each operation requires a detailed explanation of its purpose through the
-   * reason and description fields, making it clear why the API was designed and
-   * how it should be used.
-   *
-   * DO: Use object types for all request bodies and responses. DO: Reference
-   * named types defined in the components section. DO: Use `application/json`
-   * as the content-type. DO: Use `string & tags.Format<"uri">` in the schema
-   * for file upload/download operations instead of binary data formats.
-   *
-   * In OpenAPI, this might represent:
+   * RESTful API operation (excludes authorization and prerequisite fields).
    *
-   * ```json
-   * {
-   *   "/shoppings/customers/orders": {
-   *     "post": {
-   *       "description": "Create a new order application from shopping cart...",
-   *       "parameters": [...],
-   *       "requestBody": {...},
-   *       "responses": {...}
-   *     }
-   *   }
-   * }
-   * ```
+   * Use object types for request/response bodies, reference named component
+   * types, use `application/json` content-type, and `string &
+   * tags.Format<"uri">` for file operations.
    */
   export interface IOperation extends Omit<
     AutoBeOpenApi.IOperation,

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

@@ -10,10 +10,6 @@ export interface IAutoBeInterfaceOperationReviewApplication {
   /**
    * Process operation review task or preliminary data requests.
    *
-   * Analyzes the operation for security vulnerabilities, schema compliance,
-   * logical consistency, and standard adherence. Outputs structured thinking
-   * process and the production-ready operation.
-   *
    * @param props Request containing either preliminary data request or complete
    *   task
    */
@@ -25,34 +21,17 @@ export namespace IAutoBeInterfaceOperationReviewApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests (getAnalysisSections, getDatabaseSchemas, etc.):
-     *
-     * - What critical information is missing that you don't already have?
-     * - Why do you need it specifically right now?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion (complete):
+     * For preliminary requests: what critical information is missing and why?
+     * Be brief — state the gap, don't list everything you have.
      *
-     * - What key assets did you acquire?
-     * - What did you accomplish?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every single item.
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * For completion: what key assets did you acquire, what did you accomplish,
+     * why is it sufficient? Summarize — don't enumerate every single item.
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval
-     * (getAnalysisSections, getDatabaseSchemas) or final operation review
-     * (complete). When preliminary returns empty array, that type is removed
-     * from the union, physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union, physically preventing repeated calls.
      */
     request:
       | IComplete
@@ -64,109 +43,42 @@ export namespace IAutoBeInterfaceOperationReviewApplication {
   }
 
   /**
-   * Request to review and validate an API operation with minimal correction
-   * power.
-   *
-   * This agent can ONLY modify fields present in the IOperation type. For
-   * issues in fields not present in IOperation, it must reject the operation by
-   * returning null.
+   * Review and validate an API operation. Can ONLY modify IOperation fields:
    *
-   * The IOperation type contains only:
+   * - `specification`: Can fix implementation details, algorithm descriptions,
+   *   database query logic
+   * - `description`: Can fix soft delete mismatches, inappropriate security
+   *   mentions, add schema references
+   * - `requestBody`: Can modify both description and typeName
+   * - `responseBody`: Can modify both description and typeName
    *
-   * - Specification: Implementation guidance for Realize Agent - can fix
-   *   implementation details, algorithm descriptions, database query logic
-   * - Description: API documentation for consumers - can fix soft delete
-   *   mismatches, inappropriate security mentions, add schema references
-   * - RequestBody: Complete object - can modify both description and typeName to
-   *   fix clarity issues and naming convention violations
-   * - ResponseBody: Complete object - can modify both description and typeName to
-   *   fix clarity issues and naming convention violations
-   *
-   * Fields not in IOperation cannot be modified - the agent must reject by
-   * returning null if those fields have issues.
+   * Return null to reject if issues exist in non-modifiable fields (path,
+   * method, parameters, etc.).
    */
   export interface IComplete {
-    /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval or actual
-     * task execution. Value "complete" indicates this is the final task
-     * execution request.
-     */
+    /** Type discriminator for completion request. */
     type: "complete";
 
-    /**
-     * Comprehensive operation-level review findings.
-     *
-     * Systematic assessment of the operation organized by severity:
-     *
-     * - Authorization configuration issues
-     * - Path structure violations
-     * - Metadata consistency problems
-     * - Description accuracy issues
-     *
-     * Documents what issues were found during review, with specific examples
-     * and current vs expected behavior.
-     */
+    /** Operation-level review findings organized by severity. */
     review: string;
 
     /**
-     * Action plan for identified issues.
-     *
-     * Structured improvement strategy explaining what corrections will be
-     * applied and why:
-     *
-     * - What specific changes are being made
-     * - Why each change is necessary
-     * - If rejecting (returning null), why the operation cannot be fixed
-     *
-     * If no issues found: "No improvements required. Operation meets
-     * standards."
+     * Action plan for corrections, or "No improvements required. Operation
+     * meets standards."
      */
     plan: string;
 
     /**
-     * Corrected operation with issues resolved, or null if operation rejected.
-     *
-     * The agent can only modify fields present in IOperation type (description,
-     * requestBody, responseBody).
-     *
-     * Return values:
-     *
-     * - **Corrected operation**: If fixable issues were found and corrected in
-     *   the modifiable fields
-     * - **null**: If operation is perfect OR if issues exist in fields not
-     *   present in IOperation type
-     *
-     * When null is returned:
-     *
-     * - For perfect operations: means "no changes needed, proceed"
-     * - For failed validation: means "reject this operation, remove from
-     *   pipeline"
-     *
-     * The orchestrator will filter out null operations from the final operation
-     * list.
+     * Corrected operation with fixes applied. Null when no changes are needed.
+     * If issues exist in non-modifiable fields, also set to null (the `plan`
+     * field should explain why).
      */
     content: IOperation | null;
   }
 
   /**
-   * Operation with ONLY the fields that this agent can modify.
-   *
-   * This type contains ONLY the modifiable fields. Fields not in this type
-   * cannot be modified - if they have issues, the agent must return null.
-   *
-   * Fields in this type:
-   *
-   * - **specification**: Implementation guidance for Realize Agent - can fix
-   *   implementation details, algorithm descriptions, database query logic
-   * - **description**: API documentation for consumers - can fix soft delete
-   *   mismatches, remove inappropriate security mentions, add schema
-   *   references
-   * - **requestBody**: Complete request body object (or null) - can modify both
-   *   description and typeName to fix naming conventions or improve clarity
-   * - **responseBody**: Complete response body object (or null) - can modify both
-   *   description and typeName to fix naming conventions or improve clarity
+   * Operation subset containing only modifiable fields. Return null if
+   * non-modifiable fields have issues.
    */
   export interface IOperation extends Pick<
     AutoBeOpenApi.IOperation,

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

@@ -10,52 +10,21 @@ import { IAutoBePreliminaryGetPreviousInterfaceOperations } from "../../common/s
 import { IAutoBePreliminaryGetPreviousInterfaceSchemas } from "../../common/structures/IAutoBePreliminaryGetPreviousInterfaceSchemas";
 
 export interface IAutoBeInterfacePrerequisiteApplication {
-  /**
-   * Process prerequisite analysis task or preliminary data requests.
-   *
-   * Analyzes a single operation's dependencies and returns the complete
-   * prerequisite chain based on resource relationships.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
-   */
+  /** Process task or retrieve preliminary data. */
   process(props: IAutoBeInterfacePrerequisiteApplication.IProps): void;
 }
 
 export namespace IAutoBeInterfacePrerequisiteApplication {
   export interface IProps {
     /**
-     * Think before you act.
-     *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests (getAnalysisSections, getDatabaseSchemas, etc.):
-     *
-     * - What critical information is missing that you don't already have?
-     * - Why do you need it specifically right now?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion (complete):
-     *
-     * - What key assets did you acquire?
-     * - What did you accomplish?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every single item.
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * Reasoning about your current state: what's missing (preliminary) or what
+     * you accomplished (completion).
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval
-     * (getAnalysisSections, getDatabaseSchemas, getInterfaceOperations,
-     * getInterfaceSchemas) or final prerequisite analysis (complete). When
-     * preliminary returns empty array, that type is removed from the union,
-     * physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union.
      */
     request:
       | IComplete
@@ -69,62 +38,21 @@ export namespace IAutoBeInterfacePrerequisiteApplication {
       | IAutoBePreliminaryGetPreviousInterfaceSchemas;
   }
 
-  /**
-   * Request to analyze and generate API operation prerequisites.
-   *
-   * Executes prerequisite analysis to determine which Available API Operations
-   * must be executed before the target operation based on resource creation
-   * dependencies and existence validations.
-   */
+  /** Request to analyze and generate API operation prerequisites. */
   export interface IComplete {
-    /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval or actual
-     * task execution. Value "complete" indicates this is the final task
-     * execution request.
-     */
+    /** Type discriminator for completion request. */
     type: "complete";
 
-    /**
-     * Analysis of the operation's resource dependencies.
-     *
-     * Before determining prerequisites, analyze what you know:
-     *
-     * - What resources does this operation require to exist?
-     * - What foreign key relationships affect this operation?
-     * - What path parameters imply resource dependencies?
-     * - What request body fields reference other resources?
-     */
+    /** Analysis of the operation's resource dependencies. */
     analysis: string;
 
-    /**
-     * Rationale for the prerequisite chain decisions.
-     *
-     * Explain why you selected these prerequisites:
-     *
-     * - Why is each prerequisite operation necessary?
-     * - What resource must exist before this operation can succeed?
-     * - What is the correct ordering of prerequisite operations?
-     * - What prerequisites were excluded and why?
-     */
+    /** Rationale for the prerequisite chain decisions. */
     rationale: string;
 
-    /**
-     * The API endpoint being analyzed.
-     *
-     * Identifies the specific operation (method + path) that needs
-     * prerequisites.
-     */
+    /** The API endpoint (method + path) being analyzed. */
     endpoint: AutoBeOpenApi.IEndpoint;
 
-    /**
-     * Required prerequisite operations.
-     *
-     * List of API operations that must be successfully executed before this
-     * operation can be performed. Based on resource creation dependencies and
-     * existence validations from the analysis.
-     */
+    /** Required prerequisite operations that must execute before this operation. */
     prerequisites: AutoBeOpenApi.IPrerequisite[];
   }
 }

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

@@ -9,54 +9,21 @@ import { IAutoBePreliminaryGetPreviousInterfaceOperations } from "../../common/s
 import { IAutoBePreliminaryGetPreviousInterfaceSchemas } from "../../common/structures/IAutoBePreliminaryGetPreviousInterfaceSchemas";
 
 export interface IAutoBeInterfaceSchemaApplication {
-  /**
-   * Process schema generation task or preliminary data requests.
-   *
-   * Generates OpenAPI components containing named schema types and integrates
-   * them into the final OpenAPI specification. Processes all entity schemas,
-   * their variants, and related type definitions to ensure comprehensive and
-   * consistent API design.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
-   */
+  /** Process task or retrieve preliminary data. */
   process(props: IAutoBeInterfaceSchemaApplication.IProps): void;
 }
 
 export namespace IAutoBeInterfaceSchemaApplication {
   export interface IProps {
     /**
-     * Think before you act.
-     *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests (getAnalysisSections, getDatabaseSchemas, etc.):
-     *
-     * - What critical information is missing that you don't already have?
-     * - Why do you need it specifically right now?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion (complete):
-     *
-     * - What key assets did you acquire?
-     * - What did you accomplish?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every single item.
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * Reasoning about your current state: what's missing (preliminary) or what
+     * you accomplished (completion).
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval
-     * (getAnalysisSections, getDatabaseSchemas, getInterfaceOperations) or
-     * final schema generation (complete). When preliminary returns empty array,
-     * that type is removed from the union, physically preventing repeated
-     * calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union.
      */
     request:
       | IComplete
@@ -69,52 +36,20 @@ export namespace IAutoBeInterfaceSchemaApplication {
       | IAutoBePreliminaryGetPreviousInterfaceSchemas;
   }
 
-  /**
-   * Request to generate a single OpenAPI schema component.
-   *
-   * Executes schema generation to create a type definition for a specific DTO
-   * type. Each invocation handles one schema component to ensure accuracy and
-   * clear responsibility.
-   */
+  /** Request to generate a single OpenAPI schema component. */
   export interface IComplete {
-    /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform: preliminary data retrieval or actual
-     * task execution. Value "complete" indicates this is the final task
-     * execution request.
-     */
+    /** Type discriminator for completion request. */
     type: "complete";
 
-    /**
-     * Analysis of the type's purpose and context.
-     *
-     * Before designing the schema, analyze what you know:
-     *
-     * - What is this type for? (e.g., IProduct.ICreate is a creation request)
-     * - What database entities or operations inform its structure?
-     * - What fields should be included based on the variant type?
-     * - Are there related types that provide structural hints?
-     */
+    /** Analysis of the type's purpose and context. */
     analysis: string;
 
-    /**
-     * Rationale for the schema design decisions.
-     *
-     * Explain why you designed the schema this way:
-     *
-     * - Which properties did you include and why?
-     * - What is required vs optional, and why?
-     * - Which types use $ref and why?
-     * - What was excluded and why? (e.g., auto-generated fields for ICreate)
-     */
+    /** Rationale for the schema design decisions. */
     rationale: string;
 
     /**
-     * Design structure for the schema being generated.
-     *
-     * Contains `databaseSchema`, `specification`, `description`, and `schema`
-     * fields that together define a complete DTO type component.
+     * Schema design: database mapping, specification, description, and JSON
+     * Schema.
      */
     design: AutoBeInterfaceSchemaDesign;
   }