@autobe/agent 0.30.4 → 0.30.5

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

@@ -6,10 +6,6 @@ export interface IAutoBeRealizeCollectorCorrectApplication {
   /**
    * Process collector correction task or preliminary data requests.
    *
-   * Systematically analyzes and corrects TypeScript compilation errors in
-   * collector functions through three-phase workflow (think → draft → revise).
-   * Maintains business logic integrity while resolving all compilation issues.
-   *
    * @param props Request containing either preliminary data request or complete
    *   task
    */
@@ -21,66 +17,34 @@ export namespace IAutoBeRealizeCollectorCorrectApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests (getDatabaseSchemas):
-     *
-     * - 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?
      *
-     * - 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 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
-     * (getDatabaseSchemas) or final error correction (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 | IAutoBePreliminaryGetDatabaseSchemas;
   }
 
-  /**
-   * Request to correct collector implementation errors.
-   *
-   * Executes three-phase error correction to resolve TypeScript compilation
-   * issues in collector functions. Applies systematic fixes following think →
-   * draft → revise pattern to ensure error-free production code.
-   */
+  /** Correct collector compilation errors via think/draft/revise. */
   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";
 
     /**
-     * Systematic error analysis and correction strategy.
-     *
-     * MUST contain thorough analysis with these four mandatory sections:
+     * Systematic error analysis. MUST contain four sections:
      *
-     * 1. Error Inventory - Categorize ALL compilation errors by root cause type
-     * 2. Root Cause Analysis - Identify WHY each error occurs (wrong field, type
+     * 1. Error Inventory — categorize ALL compilation errors by root cause
+     * 2. Root Cause Analysis — identify WHY each error occurs (wrong field, type
      *    mismatch, etc.)
-     * 3. Schema Verification - Cross-check error-related fields against actual
+     * 3. Schema Verification — cross-check error-related fields against actual
      *    database schema
-     * 4. Correction Strategy - Specific fix for each error (not workarounds)
+     * 4. Correction Strategy — specific fix for each error (not workarounds)
      *
      * This forces you to understand the REAL problem (not guess) and plan
      * surgical fixes that address root causes, not symptoms.
@@ -88,103 +52,57 @@ export namespace IAutoBeRealizeCollectorCorrectApplication {
     think: string;
 
     /**
-     * Field-by-field mapping verification for complete coverage.
+     * Field-by-field mapping verification. For each database schema member:
      *
-     * Review EVERY field and relation from the database schema to ensure
-     * correct handling. This systematic approach catches errors beyond what the
-     * compiler reports and prevents new issues.
-     *
-     * For each database schema member, document:
-     *
-     * - `member`: Exact field/relation name from database schema
-     * - `kind`: Whether it's a scalar field, belongsTo, hasOne, or hasMany
-     *   relation
-     * - `nullable`: Whether the field/relation is nullable (true/false for
-     *   scalar/belongsTo, null for hasMany/hasOne)
+     * - `member`: Exact Prisma field/relation name — verify against schema
+     * - `kind`: scalar, belongsTo, hasOne, or hasMany
+     * - `nullable`: true/false for scalar/belongsTo, null for hasMany/hasOne
      * - `how`: Current state + correction plan ("No change needed", "Fix:
-     *   [problem] → [solution]", etc.)
-     *
-     * The `kind` property forces you to consciously identify whether each
-     * member is a scalar or relation BEFORE deciding how to fix it. This
-     * prevents common correction errors like treating belongsTo relations as
-     * scalar fields.
-     *
-     * The `nullable` property forces you to explicitly identify nullability
-     * constraints BEFORE deciding correction strategy. This prevents errors
-     * like assigning null to non-nullable fields or using null instead of
-     * undefined for optional belongsTo relations.
+     *   [problem] → [solution]")
      *
-     * Even fields without errors should be included with "No change needed" to
-     * ensure complete review. Missing even a single field could hide bugs.
+     * Even fields without errors must be included with "No change needed" to
+     * ensure complete review. MUST include EVERY field/relation from the
+     * database schema.
      *
-     * This structured verification:
-     *
-     * - Catches silent errors compiler didn't report
-     * - Ensures no fields accidentally omitted
-     * - Forces explicit classification (kind + nullable) before correction (how)
-     * - Prevents confusion between scalar fields and relations
-     * - Prevents null assignment errors through explicit nullability tracking
-     * - Documents correction decisions explicitly
-     * - Prevents regression in working fields
-     *
-     * The validator will cross-check this against the database schema to ensure
-     * nothing was overlooked.
+     * Missing even a single field will cause validation failure.
      */
     mappings: AutoBeRealizeCollectorMapping[];
 
     /**
-     * Initial correction implementation.
-     *
-     * Complete corrected code that applies ALL fixes from the think phase
-     * strategy. EVERY error in think Section 1 inventory MUST be addressed.
-     * Implement:
+     * Complete corrected code. EVERY error from think Section 1 MUST be
+     * addressed. Implement:
      *
      * - Field name corrections (exact names from database schema)
      * - Type fixes (proper CreateInput types, nullable handling)
      * - Neighbor collector reuse (replace inline logic if collector exists)
      * - Relationship fixes (connect/create syntax)
      *
-     * Apply fixes surgically - change ONLY what's broken, preserve working
+     * Apply fixes surgically — change ONLY what's broken, preserve working
      * logic.
      */
     draft: string;
 
-    /**
-     * Revision and finalization phase.
-     *
-     * Reviews the draft corrections and produces the final, error-free code
-     * that maintains all business requirements.
-     */
+    /** Reviews draft corrections and produces final error-free code. */
     revise: IReviseProps;
   }
 
   export interface IReviseProps {
     /**
-     * Critical correction review and validation.
+     * MUST systematically verify four checklists:
      *
-     * MUST systematically verify using four checklists:
+     * 1. Error Resolution — confirm EVERY error from think Section 1 is fixed
+     * 2. Root Cause Fix — verify fixes address root causes (not workarounds/hacks)
+     * 3. System Rules — neighbor reuse, proper types, no fabricated fields
+     * 4. No Regression — confirm no NEW errors, business logic intact
      *
-     * 1. Error Resolution - Confirm EVERY error from think Section 1 is fixed
-     * 2. Root Cause Fix - Verify fixes address root causes (not workarounds/hacks)
-     * 3. System Rules - Mandatory neighbor reuse, proper types, no fabricated
-     *    fields
-     * 4. No Regression - Confirm no NEW errors introduced, business logic intact
-     *
-     * Identify any remaining issues with line numbers and root cause analysis.
      * Catch Band-Aid fixes (type assertions, any casts) that hide real
      * problems.
      */
     review: string;
 
     /**
-     * Final error-free collector code with all corrections applied.
-     *
-     * Apply ALL remaining fixes identified in the review to produce
-     * compilation-ready code. If review found issues (workarounds, new errors),
-     * this MUST contain proper fixes.
-     *
-     * Return `null` ONLY if draft is already perfect and review found zero
-     * issues.
+     * Final error-free code with all corrections applied, or null if draft
+     * needs no changes.
      */
     final: string | null;
   }

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

@@ -6,27 +6,17 @@ import { IAutoBePreliminaryGetInterfaceOperations } from "../../common/structure
 import { IAutoBePreliminaryGetInterfaceSchemas } from "../../common/structures/IAutoBePreliminaryGetInterfaceSchemas";
 
 /**
- * Function calling interface for planning collector DTO generation.
+ * Plans whether a single DTO needs a collector. Sets databaseSchemaName to null
+ * for non-collectable DTOs.
  *
- * Guides the AI agent through analyzing a single DTO type and determining
- * whether it needs a collector. Each DTO is analyzed independently, enabling
- * parallel processing across all DTOs.
- *
- * The planning follows a structured RAG workflow: preliminary context gathering
- * (database schemas, DTO schemas, Operations) → eligibility analysis → plan
- * generation.
- *
- * **Key Decisions**: Not all DTOs require collectors. The agent must
- * distinguish collectable DTOs (Create DTO + DB-backed + Direct mapping) from
- * non-collectable DTOs (read-only DTOs, computed types) and set
- * databaseSchemaName to null for non-collectable ones.
+ * **Key Decisions**: Not all DTOs require collectors. Distinguish collectable
+ * DTOs (Create DTO + DB-backed + direct mapping) from non-collectable DTOs
+ * (read-only DTOs, computed types).
  */
 export interface IAutoBeRealizeCollectorPlanApplication {
   /**
-   * Process collector planning task or preliminary data requests.
-   *
    * Analyzes the given DTO type and generates a plan entry determining whether
-   * a collector is needed. Returns exactly ONE plan entry for the given DTO.
+   * a collector is needed. Returns exactly ONE plan entry.
    *
    * @param props Request containing either preliminary data request or complete
    *   plan
@@ -38,39 +28,17 @@ export namespace IAutoBeRealizeCollectorPlanApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your plan, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests:
+     * For preliminary requests: what schemas (database, DTO, operations) are
+     * missing?
      *
-     * - What schemas (database, DTO, Operations) are missing that you need?
-     * - Why do you need them for planning?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion:
-     *
-     * - Is this DTO collectable or non-collectable?
-     * - What database table does it map to (if collectable)?
-     * - Why is it non-collectable (if applicable)?
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * For completion: is this DTO collectable or non-collectable? What database
+     * table does it map to (if collectable)?
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform:
-     *
-     * - "getDatabaseSchemas": Retrieve database table schemas for DB structure
-     * - "getAnalysisSections": Retrieve analysis sections for context
-     * - "getInterfaceOperations": Retrieve operation specifications
-     * - "getInterfaceSchemas": Retrieve DTO type definitions for API contracts
-     * - "complete": Generate final collector plan
-     *
-     * The preliminary types are removed from the union after their respective
-     * data has been provided, physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union, physically preventing repeated calls.
      */
     request:
       | IComplete
@@ -81,96 +49,51 @@ export namespace IAutoBeRealizeCollectorPlanApplication {
   }
 
   /**
-   * Request to complete collector planning.
-   *
-   * Generates a plan with exactly ONE entry for the given DTO, indicating
-   * whether it is collectable (has database schema name) or non-collectable
-   * (null).
+   * Generates exactly ONE plan entry indicating collectable (has DB schema
+   * name) or not (null).
    */
   export interface IComplete {
     /** Type discriminator for completion request. */
     type: "complete";
 
     /**
-     * Plan entry for the given DTO.
-     *
-     * Must contain exactly ONE entry with:
-     *
-     * - DTO type name matching the given DTO
-     * - Chain of thought explaining the analysis
-     * - Database schema name if collectable, or null if not
-     *
-     * Use databaseSchemaName to distinguish:
-     *
-     * - Non-null: Collectable DTO, collector will be generated
-     * - Null: Non-collectable DTO, no collector needed
+     * Exactly ONE entry. databaseSchemaName non-null = collectable, null = no
+     * collector needed.
      */
     plans: IPlan[];
   }
 
-  /**
-   * Plan for a single DTO analysis result.
-   *
-   * Records the planning decision for one DTO from the operation request.
-   */
+  /** Planning decision for one DTO. */
   export interface IPlan {
     /**
-     * DTO type name being analyzed.
-     *
-     * The TypeScript interface type from the operation request body.
-     *
-     * Example: "IShoppingSale.ICreate", "IShoppingCategory.ICreate"
+     * TypeScript interface type from the operation request body (e.g.,
+     * "IShoppingSale.ICreate").
      */
     dtoTypeName: string;
 
     /**
-     * Chain of thought for this DTO's planning decision.
-     *
-     * Explains the agent's reasoning:
-     *
-     * - For collectable DTOs: Why a collector is needed, which database table it
-     *   maps to
-     * - For non-collectable DTOs: Why no collector is needed (read-only DTO,
-     *   computed type, etc.)
+     * Reasoning for this DTO's planning decision.
      *
-     * Example (collectable): "Collects IShoppingSale.ICreate to shopping_sales
-     * with nested category"
+     * Collectable: "Collects IShoppingSale.ICreate to shopping_sales with
+     * nested category".
      *
-     * Example (non-collectable): "IShoppingSale is read-only response DTO, not
-     * for creation"
+     * Non-collectable: "IShoppingSale is read-only response DTO, not for
+     * creation".
      */
     thinking: string;
 
     /**
-     * Database schema name if collectable, null if not.
-     *
-     * - **Non-null**: The database table name this DTO maps to. A collector will
-     *   be generated for this DTO.
-     * - **Null**: This DTO is non-collectable (read-only DTO, computed type). No
-     *   collector will be generated.
-     *
-     * Examples:
-     *
-     * - (collectable): "shopping_sales", "shopping_categories"
-     * - (non-collectable): null
+     * Database table name if collectable (e.g., "shopping_sales"), null if
+     * non-collectable (read-only DTO, computed type).
      */
     databaseSchemaName: string | null;
 
     /**
      * Referenced entities from path parameters or auth context.
      *
-     * Each reference contains:
-     *
-     * - `databaseSchemaName`: Database table name (e.g., "shopping_sales")
-     * - `source`: Origin of reference
-     *
-     *   - "from path parameter {paramName}"
-     *   - "from authorized actor"
-     *   - "from authorized session"
-     *
-     * See `AutoBeRealizeCollectorReference` for details.
-     *
-     * Empty array means the Create DTO contains all necessary references.
+     * Each reference contains `databaseSchemaName` and `source` (e.g., "from
+     * path parameter {id}", "from authorized actor"). Empty array means the
+     * Create DTO contains all necessary references.
      */
     references: AutoBeRealizeCollectorReference[];
   }

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

@@ -3,27 +3,13 @@ import { AutoBeRealizeCollectorMapping } from "@autobe/interface";
 import { IAutoBePreliminaryGetDatabaseSchemas } from "../../common/structures/IAutoBePreliminaryGetDatabaseSchemas";
 
 /**
- * Function calling interface for generating DTO collector functions.
- *
- * Guides the AI agent through creating reusable collector modules that prepare
- * database input data from API request DTOs (API → DB). Each collector handles
- * complex nested relationships, UUID generation, and proper Prisma
- * connect/create syntax.
- *
- * The generation follows a structured RAG workflow: preliminary context
- * gathering (database schemas only) → implementation planning → code generation
- * → review and refinement. All necessary DTO type information is obtained
- * transitively from the DTO type names provided in the plan
- * (AutoBeRealizeCollectorPlan).
+ * Generates collector functions that convert API request DTOs to Prisma
+ * database inputs (API → DB) via plan/draft/revise workflow.
  */
 export interface IAutoBeRealizeCollectorWriteApplication {
   /**
    * Process collector generation task or preliminary data requests.
    *
-   * Generates complete collector module through three-phase workflow (plan →
-   * draft → revise). Ensures type safety, proper database input types, and
-   * correct relationship handling.
-   *
    * @param props Request containing either preliminary data request or complete
    *   task
    */
@@ -35,78 +21,36 @@ export namespace IAutoBeRealizeCollectorWriteApplication {
     /**
      * Think before you act.
      *
-     * Before requesting preliminary data or completing your task, reflect on
-     * your current state and explain your reasoning:
-     *
-     * For preliminary requests:
-     *
-     * - What database schemas are missing that you need?
-     * - Why do you need them for collector generation?
-     * - Be brief - state the gap, don't list everything you have.
-     *
-     * For completion:
+     * For preliminary requests: what database schemas are missing and why?
      *
-     * - What schemas did you acquire?
-     * - What collector patterns did you implement?
-     * - Why is it sufficient to complete?
-     * - Summarize - don't enumerate every field mapping.
+     * For completion: what schemas did you acquire, what patterns did you
+     * implement, and why is it sufficient? Summarize — don't enumerate every
+     * field.
      *
-     * Note: All necessary DTO type information is available transitively from
-     * the DTO type names in the plan. You only need to request database
-     * schemas.
-     *
-     * This reflection helps you avoid duplicate requests and premature
-     * completion.
+     * Note: All DTO type information is available transitively from the plan's
+     * DTO type names. You only need to request database schemas.
      */
     thinking: string;
 
     /**
-     * Type discriminator for the request.
-     *
-     * Determines which action to perform:
-     *
-     * - "getDatabaseSchemas": Retrieve database table schemas for DB structure
-     * - "complete": Generate final collector implementation
-     *
-     * All necessary DTO type information is obtained transitively from the DTO
-     * type names provided in the plan (AutoBeRealizeCollectorPlan). Each DTO
-     * type name allows the system to recursively fetch all referenced types,
-     * providing complete type information without requiring explicit schema
-     * requests.
-     *
-     * The preliminary types are removed from the union after their respective
-     * data has been provided, physically preventing repeated calls.
+     * Action to perform. Exhausted preliminary types are removed from the
+     * union, physically preventing repeated calls.
      */
     request: IComplete | IAutoBePreliminaryGetDatabaseSchemas;
   }
 
-  /**
-   * Request to generate collector module implementation.
-   *
-   * Executes three-phase generation to create complete collector with:
-   *
-   * - Collect() function: Converts DTO to database input
-   * - Proper handling of nested relationships
-   * - UUID generation for new records
-   * - Type-safe Prisma create/connect syntax
-   *
-   * Follows plan → draft → revise pattern to ensure type safety and correct
-   * relationship handling.
-   */
+  /** Generate collector module via plan/draft/revise. */
   export interface IComplete {
     /** Type discriminator for completion request. */
     type: "complete";
 
     /**
-     * Collector implementation plan and strategy.
-     *
-     * MUST contain thorough analysis with these four mandatory sections:
+     * Collector implementation plan. MUST contain four sections:
      *
-     * 1. Database Schema Field Inventory - List ALL fields with exact names from
-     *    schema
-     * 2. DTO Property Inventory - List ALL properties with types
-     * 3. Field-by-Field Mapping Strategy - Explicit mapping table for every field
-     * 4. Edge Cases and Special Handling - Nullable, arrays, conditionals
+     * 1. Database Schema Field Inventory — ALL fields with exact names from schema
+     * 2. DTO Property Inventory — ALL properties with types
+     * 3. Field-by-Field Mapping Strategy — explicit mapping for every field
+     * 4. Edge Cases and Special Handling — nullable, arrays, conditionals
      *
      * This forces you to READ the actual schema (not imagine it) and creates an
      * explicit specification that the draft must implement.
@@ -114,93 +58,56 @@ export namespace IAutoBeRealizeCollectorWriteApplication {
     plan: string;
 
     /**
-     * Field-by-field mapping table for complete database coverage.
+     * Field-by-field mapping for complete database coverage.
      *
-     * MUST include EVERY field and relation from the database schema - no
+     * MUST include EVERY field and relation from the database schema — no
      * exceptions. Each mapping specifies:
      *
-     * - `member`: Exact field/relation name from database schema
-     * - `kind`: Whether it's a scalar field, belongsTo, hasOne, or hasMany
-     *   relation
-     * - `nullable`: Whether the field/relation is nullable (true/false for
-     *   scalar/belongsTo, null for hasMany/hasOne)
+     * - `member`: Exact Prisma field/relation name — read from schema, NOT from
+     *   DTO property names or FK column names
+     * - `kind`: scalar, belongsTo, hasOne, or hasMany
+     * - `nullable`: true/false for scalar/belongsTo, null for hasMany/hasOne
      * - `how`: How to obtain/generate the value for that field
      *
-     * The `kind` property forces explicit classification of each member BEFORE
-     * deciding how to handle it, preventing common errors like treating
-     * belongsTo relations as scalar fields.
-     *
-     * The `nullable` property forces explicit identification of nullability
-     * constraints BEFORE deciding handling strategy, preventing errors like
-     * assigning null to non-nullable fields or using null instead of undefined
-     * for optional relations.
-     *
-     * Missing even a single field will cause validation failure and trigger
-     * regeneration.
+     * The `kind` property forces explicit classification BEFORE deciding how to
+     * handle it, preventing errors like treating belongsTo as scalar.
      *
-     * This structured approach:
-     *
-     * - Prevents field omissions through systematic coverage
-     * - Forces explicit decision-making for each field (kind + nullable + how)
-     * - Prevents confusion between scalar fields and relations
-     * - Prevents null assignment errors through explicit nullability tracking
-     * - Enables validation before code generation
-     * - Creates clear documentation of field handling strategy
-     *
-     * The validator will cross-check this list against the actual database
-     * schema and reject incomplete mappings.
+     * Missing even a single field will cause validation failure.
      */
     mappings: AutoBeRealizeCollectorMapping[];
 
     /**
-     * Initial collector implementation draft.
-     *
-     * Complete implementation that strictly follows the plan's mapping table.
-     * EVERY field in the plan's Section 3 mapping strategy MUST appear in this
-     * draft. Implement:
+     * Complete implementation following plan's mapping table. EVERY field from
+     * plan Section 3 MUST appear. Implement:
      *
      * - Namespace with collect() function
-     * - All field mappings from plan (direct, connect, nested create)
+     * - All field mappings (direct, connect, nested create)
      * - Neighbor collector reuse (NEVER inline when collector exists)
      * - UUID generation with v4(), proper Prisma CreateInput types
      */
     draft: string;
 
-    /**
-     * Revision and finalization phase.
-     *
-     * Reviews the draft implementation and produces the final code with all
-     * improvements and corrections applied.
-     */
+    /** Reviews draft and produces final code. */
     revise: IReviseProps;
   }
 
   export interface IReviseProps {
     /**
-     * Critical review and improvement analysis.
+     * MUST systematically verify four checklists:
      *
-     * MUST systematically verify using four checklists:
+     * 1. Schema Fidelity — cross-check EVERY field name against plan Section 1
+     * 2. Plan Adherence — verify EVERY mapping from Section 3 is implemented
+     * 3. System Rules — neighbor reuse, props structure, satisfies type
+     * 4. Type Safety — compilation check, nullable handling, async/await
      *
-     * 1. Schema Fidelity - Cross-check EVERY field name against plan Section 1
-     *    inventory
-     * 2. Plan Adherence - Verify EVERY mapping from plan Section 3 is implemented
-     * 3. System Rules - Mandatory neighbor reuse, props structure, satisfies type
-     * 4. Type Safety - Compilation check, nullable handling, async/await
-     *
-     * Identify specific issues with line numbers and provide clear reasoning.
-     * This catches hallucinated fields, missing mappings, and rule violations.
+     * Identify issues with line numbers. This catches hallucinated fields,
+     * missing mappings, and rule violations.
      */
     review: string;
 
     /**
-     * Final collector code with all review improvements applied.
-     *
-     * Apply ALL fixes identified in the review to produce production-ready
-     * code. If review found issues, this MUST contain the corrected
-     * implementation.
-     *
-     * Return `null` ONLY if the draft is already perfect and review found zero
-     * issues.
+     * Final collector code with all review improvements applied, or null if
+     * draft needs no changes.
      */
     final: string | null;
   }