@autobe/agent 0.30.4 → 0.30.5

package/lib/orchestrate/realize/structures/IAutoBeRealizeCollectorCorrectApplication.d.ts

@@ -4,10 +4,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
      */
@@ -18,162 +14,84 @@ export declare 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. */
     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.
          */
         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;
     }
     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/lib/orchestrate/realize/structures/IAutoBeRealizeCollectorPlanApplication.d.ts

@@ -4,27 +4,17 @@ import { IAutoBePreliminaryGetDatabaseSchemas } from "../../common/structures/IA
 import { IAutoBePreliminaryGetInterfaceOperations } from "../../common/structures/IAutoBePreliminaryGetInterfaceOperations";
 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
@@ -36,127 +26,60 @@ export declare 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 | IAutoBePreliminaryGetDatabaseSchemas | IAutoBePreliminaryGetAnalysisSections | IAutoBePreliminaryGetInterfaceOperations | IAutoBePreliminaryGetInterfaceSchemas;
     }
     /**
-     * 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).
      */
     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. */
     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/lib/orchestrate/realize/structures/IAutoBeRealizeCollectorWriteApplication.d.ts

@@ -1,27 +1,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
      */
@@ -32,164 +18,85 @@ export declare 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. */
     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.
          */
         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;
     }
     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;
     }