@autobe/agent 0.30.4 → 0.30.5

package/src/orchestrate/analyze/structures/IAutoBeAnalyzeSectionReviewApplication.ts

@@ -1,66 +1,33 @@
 import { IAutoBePreliminaryGetPreviousAnalysisSections } from "../../common/structures/IAutoBePreliminaryGetPreviousAnalysisSections";
 
 /**
- * Application interface for the Cross-File Section Review agent.
- *
- * This agent reviews ALL files' section content together in a single LLM call,
- * providing cross-file validation for value consistency, terminology, Mermaid
- * diagram style, and EARS format (03-functional-requirements, 04-business-rules
- * only).
+ * Reviews all files' section content for cross-file value consistency,
+ * terminology, Mermaid style, and EARS format.
  */
 export interface IAutoBeAnalyzeSectionReviewApplication {
-  /**
-   * Process cross-file section review task or preliminary data requests.
-   *
-   * Reviews and validates section content across ALL files in a single call,
-   * ensuring cross-file consistency and uniformity.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
-   */
+  /** Review section content across all files for cross-file consistency. */
   process(props: IAutoBeAnalyzeSectionReviewApplicationProps): void;
 }
 
 export interface IAutoBeAnalyzeSectionReviewApplicationProps {
   /**
-   * 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 additional context do you need for cross-file validation?
-   *
-   * For completion:
-   *
-   * - Is EARS format consistent across requirement files (03, 04)?
-   * - Are values and constraints consistent across all files?
-   * - Is terminology aligned across all files?
-   * - Are Mermaid diagram styles uniform?
+   * Reasoning about your current state: what's missing (preliminary) or what
+   * you accomplished (completion).
    */
   thinking?: string | null;
 
-  /** Type discriminator for the request. */
+  /** Action to perform. Exhausted preliminary types are removed from the union. */
   request:
     | IAutoBeAnalyzeSectionReviewApplicationComplete
     | IAutoBePreliminaryGetPreviousAnalysisSections;
 }
 
-/**
- * Request to complete the cross-file section review.
- *
- * Provides per-file review verdicts for all files' section content.
- */
+/** Complete the cross-file section review with per-file verdicts. */
 export interface IAutoBeAnalyzeSectionReviewApplicationComplete {
-  /** Type discriminator for the request. */
+  /** Type discriminator for completion request. */
   type: "complete";
 
-  /**
-   * Per-file review results.
-   *
-   * Each entry contains the verdict for one file's section content.
-   */
+  /** Per-file review results. */
   fileResults: IAutoBeAnalyzeSectionReviewApplicationFileResult[];
 }
 
@@ -69,56 +36,29 @@ export interface IAutoBeAnalyzeSectionReviewApplicationFileResult {
   /** Index of the file in the scenario's files array. */
   fileIndex: number;
 
-  /**
-   * Whether this file's section content passed review.
-   *
-   * If true: File's sections are consistent with other files. If false: File's
-   * sections must be regenerated with feedback.
-   */
+  /** Whether this file's section content passed review. */
   approved: boolean;
 
   /**
-   * Detailed review feedback for this file's section content.
-   *
-   * Cross-file review criteria evaluated:
-   *
-   * - EARS format compliance (03-functional-requirements, 04-business-rules only)
-   * - Value and constraint consistency
-   * - Terminology alignment
-   * - Mermaid diagram style uniformity
-   * - No prohibited content
-   *
-   * For rejected files:
-   *
-   * - Specific inconsistencies identified
-   * - Recommendations for alignment
+   * Cross-file review feedback. For rejected files, describe specific
+   * inconsistencies.
    */
   feedback: string;
 
   /**
-   * Structured review issues for targeted rewrites / patches.
-   *
-   * Optional for backward compatibility.
+   * Structured review issues for targeted rewrites. Optional for backward
+   * compatibility.
    */
   issues?: IAutoBeAnalyzeSectionReviewApplicationReviewIssue[] | null;
 
-  /**
-   * Revised sections for this file if modifications were made.
-   *
-   * Organized by moduleIndex and unitIndex. Set to `null` if no revisions were
-   * made.
-   */
+  /** Revised sections organized by moduleIndex/unitIndex. Null if no revisions. */
   revisedSections:
     | IAutoBeAnalyzeSectionReviewApplicationRevisedModuleSections[]
     | null;
 
   /**
-   * Specific module/unit pairs whose sections were rejected.
-   *
-   * When rejecting a file, identify EXACTLY which modules and units have
-   * problematic sections. Only these will be regenerated on retry.
-   *
-   * Set to null if all module/units need regeneration, or if approving.
+   * Module/unit pairs with rejected sections. Only these are regenerated on
+   * retry. Null if all module/units need regeneration, or if approving.
    */
   rejectedModuleUnits:
     | IAutoBeAnalyzeSectionReviewApplicationRejectedModuleUnit[]
@@ -130,59 +70,60 @@ export interface IAutoBeAnalyzeSectionReviewApplicationRejectedModuleUnit {
   /** Index of the module section. */
   moduleIndex: number;
 
-  /** Indices of units within this module that need section regeneration. */
+  /** Unit indices needing section regeneration. */
   unitIndices: number[];
 
-  /** Specific feedback for this module/unit group's issues. */
+  /** Feedback for this module/unit group's issues. */
   feedback: string;
 
   /**
-   * Structured issues scoped to this module/unit group.
-   *
-   * Optional for backward compatibility.
+   * Structured issues scoped to this module/unit group. Optional for backward
+   * compatibility.
    */
   issues?: IAutoBeAnalyzeSectionReviewApplicationReviewIssue[] | null;
 
   /**
-   * Per-unit mapping of specific section indices that need regeneration.
-   *
-   * Keys are unit indices (from `unitIndices`), values are arrays of section
-   * indices within that unit's `sectionSections[]` that failed review.
-   *
-   * When null/undefined or when a unitIndex is not present as a key, ALL
-   * sections for that unit are regenerated (backward-compatible fallback).
+   * Per-unit mapping of section indices needing regeneration. When null or a
+   * unitIndex is absent, ALL sections for that unit are regenerated.
    */
   sectionIndicesPerUnit?: Record<number, number[]> | null;
 }
 
+/** A specific review issue found during section content review. */
 export interface IAutoBeAnalyzeSectionReviewApplicationReviewIssue {
+  /** Rule violation code (e.g., "TERM-001", "VALUE-002"). */
   ruleCode: string;
+  /** Module index where the issue was found, or null if file-level. */
   moduleIndex: number | null;
+  /** Unit index where the issue was found, or null if module-level. */
   unitIndex: number | null;
+  /** Section index where the issue was found, or null if unit-level. */
   sectionIndex?: number | null;
+  /** Specific instruction for fixing this issue. */
   fixInstruction: string;
+  /** Supporting evidence from the source text. */
   evidence?: string | null;
 }
 
-/** Structure for revised sections of a single module. */
+/** Revised sections of a single module. */
 export interface IAutoBeAnalyzeSectionReviewApplicationRevisedModuleSections {
   /** Index of the module section. */
   moduleIndex: number;
 
-  /** Revised sections for each unit in this module. */
+  /** Revised sections for each unit. */
   units: IAutoBeAnalyzeSectionReviewApplicationRevisedUnitSections[];
 }
 
-/** Structure for revised sections of a single unit. */
+/** Revised sections of a single unit. */
 export interface IAutoBeAnalyzeSectionReviewApplicationRevisedUnitSections {
   /** Index of the unit section. */
   unitIndex: number;
 
-  /** Revised section sections for this unit. */
+  /** Revised subsections (#### level) within this unit. */
   sectionSections: IAutoBeAnalyzeSectionReviewApplicationRevisedSectionSection[];
 }
 
-/** Structure for a revised section. */
+/** A revised section. */
 export interface IAutoBeAnalyzeSectionReviewApplicationRevisedSectionSection {
   /** Title of the section. */
   title: string;

package/src/orchestrate/analyze/structures/IAutoBeAnalyzeWriteSectionApplication.ts

@@ -1,61 +1,33 @@
 import { IAutoBePreliminaryGetPreviousAnalysisSections } from "../../common/structures/IAutoBePreliminaryGetPreviousAnalysisSections";
 
 /**
- * Application interface for the Section (###) generation agent.
- *
- * This agent is responsible for creating detailed sections within an approved
- * unit section structure, producing implementation-ready requirement
- * specifications.
+ * Generates detailed sections (###) within approved unit structures as
+ * implementation-ready specs.
  */
 export interface IAutoBeAnalyzeWriteSectionApplication {
   /**
-   * Process section generation task or preliminary data requests.
-   *
-   * Creates detailed sections for a specific unit section, including complete
-   * content with Mermaid diagrams and, for requirement-heavy files
-   * (03-functional-requirements, 04-business-rules), EARS format requirements.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
+   * Create detailed sections for a unit, with Mermaid diagrams and EARS format
+   * where applicable.
    */
   process(props: IAutoBeAnalyzeWriteSectionApplicationProps): void;
 }
 
 export interface IAutoBeAnalyzeWriteSectionApplicationProps {
   /**
-   * 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 additional context do you need for detailed content?
-   *
-   * For completion:
-   *
-   * - How do the sections address the keywords from the unit section?
-   * - For 03/04 files: Are requirements specific and in EARS format?
-   * - For other files: Is content written in clear, descriptive prose?
-   * - Are Mermaid diagrams properly formatted?
+   * Reasoning about your current state: what's missing (preliminary) or what
+   * you accomplished (completion).
    */
   thinking?: string | null;
 
-  /** Type discriminator for the request. */
+  /** Action to perform. Exhausted preliminary types are removed from the union. */
   request:
     | IAutoBeAnalyzeWriteSectionApplicationComplete
     | IAutoBePreliminaryGetPreviousAnalysisSections;
 }
 
-/**
- * Request to generate section content.
- *
- * Creates the detailed content within a unit section, including
- * implementation-ready requirements specifications with proper formatting and
- * diagrams.
- */
+/** Generate detailed section content within a unit section. */
 export interface IAutoBeAnalyzeWriteSectionApplicationComplete {
-  /** Type discriminator for the request. */
+  /** Type discriminator for completion request. */
   type: "complete";
 
   /** Index of the grandparent module section. */
@@ -64,39 +36,19 @@ export interface IAutoBeAnalyzeWriteSectionApplicationComplete {
   /** Index of the parent unit section. */
   unitIndex: number;
 
-  /**
-   * Array of sections for this unit section.
-   *
-   * Each section represents a detailed subsection (#### level) containing
-   * specific requirements, specifications, or process descriptions. The content
-   * should:
-   *
-   * - Use EARS format for requirements in 03-functional-requirements and
-   *   04-business-rules files; use natural language prose for other files
-   * - Include Mermaid diagrams with proper syntax
-   * - Be specific and implementation-ready
-   * - Avoid prohibited content (DB schemas, API specs)
-   */
+  /** Detailed subsections (#### level) for this unit. */
   sectionSections: IAutoBeAnalyzeWriteSectionApplicationSectionSection[];
 }
 
-/** Structure representing a single section. */
+/** A single section (#### level). */
 export interface IAutoBeAnalyzeWriteSectionApplicationSectionSection {
-  /**
-   * Title of the section (#### level heading).
-   *
-   * Should clearly indicate the specific requirement, process, or feature being
-   * detailed.
-   */
+  /** Section title (#### level heading). */
   title: string;
 
   /**
-   * Complete content for the section.
-   *
-   * Contains detailed requirements, specifications, and diagrams. Content
-   * guidelines:
+   * Complete section content with requirements, specs, and diagrams.
    *
-   * EARS Format (ONLY for 03-functional-requirements, 04-business-rules):
+   * EARS Format (03-functional-requirements, 04-business-rules ONLY):
    *
    * - Ubiquitous: "THE <system> SHALL <function>"
    * - Event-driven: "WHEN <trigger>, THE <system> SHALL <function>"
@@ -104,39 +56,17 @@ export interface IAutoBeAnalyzeWriteSectionApplicationSectionSection {
    * - Unwanted: "IF <condition>, THEN THE <system> SHALL <function>"
    * - Optional: "WHERE <feature>, THE <system> SHALL <function>"
    *
-   * Natural Language (for 00-toc, 01-actors-and-auth, 02-domain-model,
-   * 05-non-functional):
-   *
-   * - Use clear, descriptive prose for definitions, concepts, and policies
-   * - Focus on readability over formal structure
-   * - Tables and bullet points are preferred for structured data
-   *
-   * Mermaid Diagram Rules:
-   *
-   * - ALL labels must use double quotes: A["User Login"]
-   * - NO spaces between brackets and quotes
-   * - Arrow syntax: --> (NOT --|)
-   * - LR orientation preferred for flowcharts
-   *
-   * Prohibited Content:
-   *
-   * - Database schemas or ERD
-   * - API endpoint specifications
-   * - Technical implementation details
-   * - Frontend UI/UX specifications
-   *
-   * Hallucination Prevention:
-   *
-   * - Every requirement must trace to the original user input
-   * - Do NOT invent SLA numbers, timeout values, or performance targets
-   * - Do NOT add security mechanisms (2FA, JWT, encryption) user did not mention
-   * - Do NOT add infrastructure requirements (CDN, caching) user did not mention
-   * - 05-non-functional: only describe aspects the user explicitly mentioned
+   * Other files (00-toc, 01, 02, 05): clear descriptive prose, tables, bullet
+   * points.
    *
-   * Conciseness:
+   * Mermaid rules: ALL labels use double quotes A["Label"], no spaces before
+   * quotes, --> arrows, LR preferred.
    *
-   * - One concept = one section, not multiple sections rephrasing the same idea
-   * - 02-domain-model: max 1-3 sections per business concept
+   * NEVER include: DB schemas/ERD, API specs, implementation details, frontend
+   * UI/UX specs. Every requirement MUST trace to user input. Do NOT invent SLA
+   * numbers, timeouts, security mechanisms, or infrastructure the user did not
+   * mention. One concept = one section. 02-domain-model: max 1-3 sections per
+   * concept.
    */
   content: string;
 }

package/src/orchestrate/analyze/structures/IAutoBeAnalyzeWriteUnitApplication.ts

@@ -1,123 +1,50 @@
 import { IAutoBePreliminaryGetPreviousAnalysisSections } from "../../common/structures/IAutoBePreliminaryGetPreviousAnalysisSections";
 
-/**
- * Application interface for the Unit Section (##) generation agent.
- *
- * This agent is responsible for creating unit-level sections within an approved
- * module section structure, defining functional requirement groupings and their
- * content.
- */
+/** Generates unit-level sections (##) within approved module structures. */
 export interface IAutoBeAnalyzeWriteUnitApplication {
   /**
-   * Process unit section generation task or preliminary data requests.
-   *
-   * Creates unit-level sections for a specific module section, including
-   * section titles, purposes, content, and keywords for guiding section
-   * generation.
-   *
-   * @param props Request containing either preliminary data request or complete
-   *   task
+   * Create unit sections with titles, purposes, content, and keywords for a
+   * module.
    */
   process(props: IAutoBeAnalyzeWriteUnitApplicationProps): void;
 }
 
 export interface IAutoBeAnalyzeWriteUnitApplicationProps {
   /**
-   * 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 additional context do you need for this module section?
-   * - Why is this information necessary?
-   *
-   * For completion:
-   *
-   * - How do the unit sections align with the parent module section?
-   * - What functional areas are covered?
-   * - Are the keywords appropriate for guiding section generation?
+   * Reasoning about your current state: what's missing (preliminary) or what
+   * you accomplished (completion).
    */
   thinking?: string | null;
 
-  /** Type discriminator for the request. */
+  /** Action to perform. Exhausted preliminary types are removed from the union. */
   request:
     | IAutoBeAnalyzeWriteUnitApplicationComplete
     | IAutoBePreliminaryGetPreviousAnalysisSections;
 }
 
-/**
- * Request to generate unit section structure.
- *
- * Creates the unit-level hierarchy within a module section, including section
- * definitions with purposes, content, and keywords that will guide section
- * generation.
- */
+/** Generate unit section structure within a module section. */
 export interface IAutoBeAnalyzeWriteUnitApplicationComplete {
-  /** Type discriminator for the request. */
+  /** Type discriminator for completion request. */
   type: "complete";
 
-  /**
-   * Index of the parent module section.
-   *
-   * References which module section (0-based) these unit sections belong to.
-   * This ensures proper alignment with the approved module structure.
-   */
+  /** Index of the parent module section (0-based). */
   moduleIndex: number;
 
-  /**
-   * Array of unit sections for this module section.
-   *
-   * Each unit section represents a subsection (### level) that groups related
-   * functionality or requirements. The sections should:
-   *
-   * - Align with the parent module section's purpose
-   * - Have clear functional boundaries
-   * - Provide meaningful keywords for section guidance
-   */
+  /** Unit sections (### level) grouping related functionality. */
   unitSections: IAutoBeAnalyzeWriteUnitApplicationUnitSection[];
 }
 
-/** Structure representing a single unit section. */
+/** A single unit section. */
 export interface IAutoBeAnalyzeWriteUnitApplicationUnitSection {
-  /**
-   * Title of the unit section (### level heading).
-   *
-   * Should clearly indicate the functional area or requirement group covered by
-   * this section.
-   */
+  /** Title of the unit section (### level heading). */
   title: string;
 
-  /**
-   * Purpose statement explaining what this section covers.
-   *
-   * A brief description of the section's role within the parent module section
-   * and what requirements it addresses.
-   */
+  /** Brief purpose statement for this section's role within the parent module. */
   purpose: string;
 
-  /**
-   * Content for the unit section.
-   *
-   * The main body content that appears after the section heading, before any
-   * sections. Should provide:
-   *
-   * - Overview of the functional area
-   * - Context for the detailed requirements
-   * - Relationships to other sections
-   */
+  /** Main body content: overview, context, and relationships to other sections. */
   content: string;
 
-  /**
-   * Keywords that hint at section topics.
-   *
-   * A list of key concepts, features, or requirements that should be detailed
-   * in the sections. These keywords guide the Section Agent in generating
-   * appropriate detailed content.
-   *
-   * Example for "User Authentication" unit section: ["login", "registration",
-   * "password recovery", "session management"]
-   */
+  /** Keywords hinting at section topics to guide Section Agent generation. */
   keywords: string[];
 }

package/src/orchestrate/common/histories/transformPreviousAndLatestCorrectHistory.ts

@@ -12,9 +12,12 @@ export const transformPreviousAndLatestCorrectHistory = (
     diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[];
   }>,
 ): IAgenticaHistoryJson.IAssistantMessage[] => {
-  // console.log(printErrorHints(array.at(-1)!.script, array.at(-1)!.diagnostics));
-  return array.map((failure, i) => {
-    const isLatest = i === array.length - 1;
+  // P2-3: Summarize older failures when there are 3+ attempts
+  // Keep last 2 in full, summarize the rest
+  const summarized = summarizeOlderFailures(array);
+
+  return summarized.map((failure, i) => {
+    const isLatest = i === summarized.length - 1;
     const ts2339Hints = isLatest
       ? generateTS2339Hints(failure.diagnostics)
       : "";
@@ -26,52 +29,110 @@ export const transformPreviousAndLatestCorrectHistory = (
         ${
           isLatest
             ? "# Latest Failure"
-            : StringUtil.trim`
-              # Previous Failure
+            : failure.script === ""
+              ? StringUtil.trim`
+                # Summary of Earlier Failures
 
-              This is the previous failure for your reference.
+                ${failure.diagnostics[0]?.messageText ?? "Multiple earlier correction attempts failed."}
 
-              Never try to fix this previous failure code, but only
-              focus on the latest failure below. This is provided just
-              to give you context about your past mistakes.
+                Focus on the latest failure below and try a DIFFERENT approach.
+              `
+              : StringUtil.trim`
+                # Previous Failure
 
-              If same mistake happens again, you must try to not
-              repeat the same mistake. Change your approach to fix
-              the issue.
-            `
+                This is the previous failure for your reference.
+
+                Never try to fix this previous failure code, but only
+                focus on the latest failure below. This is provided just
+                to give you context about your past mistakes.
+
+                If same mistake happens again, you must try to not
+                repeat the same mistake. Change your approach to fix
+                the issue.
+              `
         }
 
-        ## Original Code
+        ${
+          failure.script !== ""
+            ? StringUtil.trim`
+              ## Original Code
 
-        Here is the previous code you have to review and fix.
+              Here is the previous code you have to review and fix.
 
-        \`\`\`typescript
-        ${failure.script}
-        \`\`\`
+              \`\`\`typescript
+              ${failure.script}
+              \`\`\`
 
-        ## Compilation Errors
+              ## Compilation Errors
 
-        Here are the compilation errors found in the code above.
+              Here are the compilation errors found in the code above.
 
-        \`\`\`json
-        ${JSON.stringify(failure.diagnostics)}
-        \`\`\`
+              \`\`\`json
+              ${JSON.stringify(failure.diagnostics)}
+              \`\`\`
 
-        ## Error Annotated Code
+              ## Error Annotated Code
 
-        Here is the error annotated code.
+              Here is the error annotated code.
 
-        Please refer to the annotation for the location of the error.
+              Please refer to the annotation for the location of the error.
 
-        By the way, note that, this code is only for reference purpose.
-        Never fix code from this error annotated code. You must fix
-        the original code above.
+              By the way, note that, this code is only for reference purpose.
+              Never fix code from this error annotated code. You must fix
+              the original code above.
 
-        ${printErrorHints(failure.script, failure.diagnostics)}
+              ${printErrorHints(failure.script, failure.diagnostics)}
 
-        ${ts2339Hints}
+              ${ts2339Hints}
+            `
+            : ""
+        }
       `,
       created_at: new Date().toISOString(),
     };
   });
 };
+
+/**
+ * P2-3: When there are 3+ failure attempts, summarize the older ones to prevent
+ * context bloat. Keep the last 2 in full, collapse the rest into a single
+ * summary entry.
+ */
+const summarizeOlderFailures = (
+  array: Array<{
+    script: string;
+    diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+  }>,
+): Array<{
+  script: string;
+  diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+}> => {
+  if (array.length <= 2) return array;
+
+  const olderCount = array.length - 2;
+  const olderDiagCount = array
+    .slice(0, -2)
+    .reduce((sum, f) => sum + f.diagnostics.length, 0);
+
+  const summary: {
+    script: string;
+    diagnostics: IAutoBeTypeScriptCompileResult.IDiagnostic[];
+  } = {
+    script: "",
+    diagnostics: [
+      {
+        file: array[0]!.diagnostics[0]?.file ?? null,
+        start: null,
+        length: null,
+        code: 0,
+        messageText:
+          `[Summary of ${olderCount} previous correction attempts with ` +
+          `${olderDiagCount} total errors. The same fixes were attempted but ` +
+          `failed. Focus on the latest diagnostics below and try a DIFFERENT approach.]`,
+        category: "error",
+      },
+    ],
+  };
+
+  return [summary, ...array.slice(-2)];
+};