@autobe/agent 0.24.2 → 0.25.0

package/src/context/IAutoBeApplication.ts

@@ -1,4 +1,3 @@
-import { IAutoBeApplicationProps } from "./IAutoBeApplicationProps";
 import { IAutoBeApplicationResult } from "./IAutoBeApplicationResult";
 
 /**
@@ -26,7 +25,26 @@ export interface IAutoBeApplication {
    * conversation. When executed after other agents have generated code, it can
    * also interpret change requests in the context of existing implementations.
    */
-  analyze(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+  analyze(props: {
+    /**
+     * Requirements-focused instructions extracted from user utterances.
+     *
+     * Contains AI-interpreted guidance specifically for the requirements
+     * analysis phase. Should focus ONLY on features, business rules, user
+     * stories, and functional specifications. Must NOT include database design,
+     * API patterns, or implementation details which belong to other phases.
+     *
+     * **CRITICAL**: Only include what the user actually said. NEVER fabricate
+     * or invent requirements the user didn't mention.
+     *
+     * Examples:
+     *
+     * - "Focus on inventory management with real-time stock tracking"
+     * - "Prioritize user authentication with role-based permissions"
+     * - "Emphasize order processing workflow with approval stages"
+     */
+    instruction: string;
+  }): Promise<IAutoBeApplicationResult>;
 
   /**
    * Run prisma agent.
@@ -47,7 +65,26 @@ export interface IAutoBeApplication {
    * generate ERD documentation using prisma-markdown. An internal review
    * process ensures schema quality and optimization.
    */
-  prisma(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+  prisma(props: {
+    /**
+     * Database design instructions extracted from user utterances.
+     *
+     * Contains AI-interpreted guidance specifically for the database schema
+     * design phase. Should focus ONLY on schema structure, relationships,
+     * constraints, and indexing strategies. Must NOT include API design or
+     * business logic implementation details.
+     *
+     * **CRITICAL**: Only include what the user actually said. NEVER fabricate
+     * or invent requirements the user didn't mention.
+     *
+     * Examples:
+     *
+     * - "Design flexible product catalog with variant support"
+     * - "Optimize for high-volume transaction queries"
+     * - "Implement strict referential integrity for financial data"
+     */
+    instruction: string;
+  }): Promise<IAutoBeApplicationResult>;
 
   /**
    * Run interface agent.
@@ -62,7 +99,26 @@ export interface IAutoBeApplication {
    * generated interface includes comprehensive JSDoc comments and undergoes
    * internal review for consistency.
    */
-  interface(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+  interface(props: {
+    /**
+     * API design instructions extracted from user utterances.
+     *
+     * Contains AI-interpreted guidance specifically for the API interface
+     * design phase. Should focus ONLY on endpoint patterns, request/response
+     * formats, DTO schemas, and operation specifications. Must NOT include
+     * database details or implementation logic.
+     *
+     * **CRITICAL**: Only include what the user actually said. NEVER fabricate
+     * or invent requirements the user didn't mention.
+     *
+     * Examples:
+     *
+     * - "Create RESTful endpoints with pagination for all list operations"
+     * - "Design mobile-friendly APIs with minimal response payloads"
+     * - "Follow OpenAPI 3.0 patterns with comprehensive error responses"
+     */
+    instruction: string;
+  }): Promise<IAutoBeApplicationResult>;
 
   /**
    * Run test program agent.
@@ -85,7 +141,26 @@ export interface IAutoBeApplication {
    * TypeScript compiler validation and internal review ensure test quality and
    * optimal coverage.
    */
-  test(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+  test(props: {
+    /**
+     * Testing strategy instructions extracted from user utterances.
+     *
+     * Contains AI-interpreted guidance specifically for the test code
+     * generation phase. Should focus ONLY on test scenarios, coverage
+     * priorities, edge cases, and validation strategies. Must NOT include
+     * implementation or API design details.
+     *
+     * **CRITICAL**: Only include what the user actually said. NEVER fabricate
+     * or invent requirements the user didn't mention.
+     *
+     * Examples:
+     *
+     * - "Prioritize payment flow testing with failure scenarios"
+     * - "Generate comprehensive tests for concurrent user operations"
+     * - "Focus on data integrity validation across all endpoints"
+     */
+    instruction: string;
+  }): Promise<IAutoBeApplicationResult>;
 
   /**
    * Run realize agent.
@@ -108,5 +183,25 @@ export interface IAutoBeApplication {
    * validation checks, and processes business rules according to
    * specifications.
    */
-  realize(props: IAutoBeApplicationProps): Promise<IAutoBeApplicationResult>;
+  realize(props: {
+    /**
+     * Implementation instructions extracted from user utterances.
+     *
+     * Contains AI-interpreted guidance specifically for the business logic
+     * implementation phase. Should focus ONLY on architectural patterns,
+     * performance requirements, business logic details, and service layer
+     * decisions. Must NOT include database schema or API interface
+     * specifications.
+     *
+     * **CRITICAL**: Only include what the user actually said. NEVER fabricate
+     * or invent requirements the user didn't mention.
+     *
+     * Examples:
+     *
+     * - "Implement with caching for frequently accessed data"
+     * - "Use transaction patterns for financial operations"
+     * - "Optimize for 10K concurrent users with rate limiting"
+     */
+    instruction: string;
+  }): Promise<IAutoBeApplicationResult>;
 }

package/src/context/IAutoBeApplicationProps.ts

@@ -1,4 +1,8 @@
 export interface IAutoBeApplicationProps {
-  /** The reason of the function call. */
-  reason: string;
+  /**
+   * Instructions for each agent phase redefined by AI from user's utterance.
+   * Contains specific guidance for analyze/prisma/interface/test/realize
+   * agents.
+   */
+  instruction: string;
 }

package/src/factory/createAgenticaHistory.ts

@@ -1,4 +1,8 @@
-import { AgenticaOperation, MicroAgenticaHistory } from "@agentica/core";
+import {
+  AgenticaExecuteHistory,
+  AgenticaOperation,
+  MicroAgenticaHistory,
+} from "@agentica/core";
 import {
   AutoBeAssistantMessageHistory,
   AutoBeHistory,
@@ -6,6 +10,8 @@ import {
 } from "@autobe/interface";
 import { ILlmSchema } from "@samchon/openapi";
 
+import { IAutoBeApplicationProps } from "../context/IAutoBeApplicationProps";
+
 export function createAgenticaHistory<Model extends ILlmSchema.Model>(props: {
   operations: readonly AgenticaOperation<Model>[];
   history: AutoBeHistory;
@@ -30,8 +36,8 @@ export function createAgenticaHistory<Model extends ILlmSchema.Model>(props: {
     created_at: props.history.created_at,
     type: "execute" as const,
     arguments: {
-      reason: props.history.reason,
-    },
+      instruction: props.history.instruction,
+    } satisfies IAutoBeApplicationProps,
     value: {
       success:
         props.history.type === "analyze" || props.history.type === "interface"
@@ -39,7 +45,7 @@ export function createAgenticaHistory<Model extends ILlmSchema.Model>(props: {
           : props.history.compiled.type === "success",
     },
     success: true,
-  };
+  } satisfies Partial<AgenticaExecuteHistory<Model>>;
   return {
     ...partial,
     protocol: operation.protocol as "class",
@@ -49,5 +55,5 @@ export function createAgenticaHistory<Model extends ILlmSchema.Model>(props: {
       protocol: operation.protocol as "class",
       operation: operation.toJSON(),
     }),
-  };
+  } satisfies AgenticaExecuteHistory<Model>;
 }

package/src/factory/createAutoBeContext.ts

@@ -279,7 +279,7 @@ const createDispatch = (props: {
         history: {
           type: "analyze",
           id: v7(),
-          reason: analyzeStart?.reason ?? "",
+          instruction: analyzeStart?.reason ?? "",
           prefix: event.prefix,
           roles: event.roles,
           files: event.files,
@@ -297,7 +297,7 @@ const createDispatch = (props: {
         history: {
           type: "prisma",
           id: v7(),
-          reason: prismaStart?.reason ?? "",
+          instruction: prismaStart?.reason ?? "",
           schemas: event.schemas,
           result: event.result,
           compiled: event.compiled,
@@ -315,7 +315,7 @@ const createDispatch = (props: {
         history: {
           type: "interface",
           id: v7(),
-          reason: interfaceStart?.reason ?? "",
+          instruction: interfaceStart?.reason ?? "",
           authorizations: event.authorizations,
           document: event.document,
           created_at: interfaceStart?.created_at ?? new Date().toISOString(),
@@ -332,7 +332,7 @@ const createDispatch = (props: {
         history: {
           type: "test",
           id: v7(),
-          reason: testStart?.reason ?? "",
+          instruction: testStart?.reason ?? "",
           files: event.files,
           compiled: event.compiled,
           created_at: testStart?.created_at ?? new Date().toISOString(),
@@ -349,7 +349,7 @@ const createDispatch = (props: {
         history: {
           type: "realize",
           id: v7(),
-          reason: realizeStart?.reason ?? "",
+          instruction: realizeStart?.reason ?? "",
           authorizations: event.authorizations,
           functions: event.functions,
           controllers: event.controllers,

package/src/orchestrate/analyze/histories/transformAnalyzeReviewHistories.ts

@@ -20,7 +20,11 @@ export const transformAnalyzeReviewHistories = <Model extends ILlmSchema.Model>(
   | IAgenticaHistoryJson.ISystemMessage
 > => {
   return [
-    ...transformAnalyzeWriteHistories(ctx, scenario, myFile).slice(0, -1),
+    ...transformAnalyzeWriteHistories(ctx, {
+      scenario,
+      file: myFile,
+      instruction: "",
+    }).slice(0, -2),
     {
       id: v7(),
       created_at: new Date().toISOString(),

package/src/orchestrate/analyze/histories/transformAnalyzeScenarioHistories.ts

@@ -8,6 +8,7 @@ import { AutoBeContext } from "../../../context/AutoBeContext";
 
 export function transformAnalyzeSceHistories<Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
+  instruction: string,
 ): Array<IMicroAgenticaHistoryJson> {
   return [
     ...ctx
@@ -33,5 +34,20 @@ export function transformAnalyzeSceHistories<Model extends ILlmSchema.Model>(
       `,
       created_at: new Date().toISOString(),
     },
+    {
+      id: v7(),
+      type: "assistantMessage",
+      text: StringUtil.trim`
+        ## Instructions from Requirements Discussion
+        
+        The following instructions were extracted by AI from 
+        the discussion with the user about requirements.
+        Use these to guide document structure planning and 
+        scenario definitions.
+        
+        ${instruction}
+      `,
+      created_at: new Date().toISOString(),
+    },
   ];
 }

package/src/orchestrate/analyze/histories/transformAnalyzeWriteHistories.ts

@@ -10,8 +10,11 @@ import { AutoBeContext } from "../../../context/AutoBeContext";
 
 export const transformAnalyzeWriteHistories = <Model extends ILlmSchema.Model>(
   ctx: AutoBeContext<Model>,
-  scenario: AutoBeAnalyzeScenarioEvent,
-  file: AutoBeAnalyzeFile.Scenario,
+  props: {
+    scenario: AutoBeAnalyzeScenarioEvent;
+    file: AutoBeAnalyzeFile.Scenario;
+    instruction: string;
+  },
 ): Array<
   | IAgenticaHistoryJson.IUserMessage
   | IAgenticaHistoryJson.IAssistantMessage
@@ -46,15 +49,15 @@ export const transformAnalyzeWriteHistories = <Model extends ILlmSchema.Model>(
     text: StringUtil.trim`
       ## Language
       
-      The language of the document is ${JSON.stringify(scenario.language ?? "en-US")}.
+      The language of the document is ${JSON.stringify(props.scenario.language ?? "en-US")}.
       
       ## Metadata
       
-      Prefix name of the service to create is ${scenario.prefix}
+      Prefix name of the service to create is ${props.scenario.prefix}
       and here is the list of the roles to reference.
       
       \`\`\`json
-      ${JSON.stringify(scenario.roles)}
+      ${JSON.stringify(props.scenario.roles)}
       \`\`\`
       
       Here is the entire list of the documents that would be published
@@ -64,14 +67,26 @@ export const transformAnalyzeWriteHistories = <Model extends ILlmSchema.Model>(
 
       \`\`\`json
       ${JSON.stringify(
-        scenario.files.filter((f) => f.filename !== file.filename),
+        props.scenario.files.filter((f) => f.filename !== props.file.filename),
       )}
       \`\`\`
       
       ## The document to write
       \`\`\`json
-      ${JSON.stringify(file)}
+      ${JSON.stringify(props.file)}
       \`\`\`
+
+      ## Instructions from Requirements Discussion
+      
+      The following instructions were extracted by AI from 
+      the discussion with the user about requirements.
+      If these instructions are relevant to the document you're 
+      currently writing (${props.file.filename}), incorporate 
+      them appropriately. 
+      
+      If not relevant to this specific document, ignore them.
+      
+      ${props.instruction}
     `,
   },
 ];

package/src/orchestrate/analyze/orchestrateAnalyze.ts

@@ -29,14 +29,14 @@ export const orchestrateAnalyze =
     ctx.dispatch({
       type: "analyzeStart",
       id: v7(),
-      reason: props.reason,
+      reason: props.instruction,
       step,
       created_at: startTime.toISOString(),
     });
 
     // Generate analysis scenario
     const scenario: AutoBeAnalyzeScenarioEvent | AutoBeAssistantMessageHistory =
-      await orchestrateAnalyzeScenario(ctx);
+      await orchestrateAnalyzeScenario(ctx, props.instruction);
     if (scenario.type === "assistantMessage")
       return ctx.assistantMessage(scenario);
     else ctx.dispatch(scenario);
@@ -55,6 +55,7 @@ export const orchestrateAnalyze =
             file,
             progress: writeProgress,
             promptCacheKey,
+            instruction: props.instruction,
           },
         );
         return event.file;

package/src/orchestrate/analyze/orchestrateAnalyzeScenario.ts

@@ -21,6 +21,7 @@ export const orchestrateAnalyzeScenario = async <
   Model extends ILlmSchema.Model,
 >(
   ctx: AutoBeContext<Model>,
+  instruction: string,
 ): Promise<AutoBeAnalyzeScenarioEvent | AutoBeAssistantMessageHistory> => {
   const start: Date = new Date();
   const pointer: IPointer<IAutoBeAnalyzeScenarioApplication.IProps | null> = {
@@ -32,7 +33,7 @@ export const orchestrateAnalyzeScenario = async <
       model: ctx.model,
       build: (value) => (pointer.value = value),
     }),
-    histories: transformAnalyzeSceHistories(ctx),
+    histories: transformAnalyzeSceHistories(ctx, instruction),
     enforceFunctionCall: false,
     message: StringUtil.trim`
       Design a complete list of documents and user roles for this project.

package/src/orchestrate/analyze/orchestrateAnalyzeWrite.ts

@@ -20,11 +20,12 @@ export const orchestrateAnalyzeWrite = async <Model extends ILlmSchema.Model>(
   props: {
     scenario: AutoBeAnalyzeScenarioEvent;
     file: AutoBeAnalyzeFile.Scenario;
+    instruction: string;
     progress: AutoBeProgressEventBase;
     promptCacheKey: string;
   },
 ): Promise<AutoBeAnalyzeWriteEvent> => {
-  const { scenario, file, progress, promptCacheKey } = props;
+  const { file, progress, promptCacheKey } = props;
   const pointer: IPointer<IAutoBeAnalyzeWriteApplication.IProps | null> = {
     value: null,
   };
@@ -34,7 +35,7 @@ export const orchestrateAnalyzeWrite = async <Model extends ILlmSchema.Model>(
       model: ctx.model,
       pointer,
     }),
-    histories: transformAnalyzeWriteHistories(ctx, scenario, file),
+    histories: transformAnalyzeWriteHistories(ctx, props),
     enforceFunctionCall: true,
     promptCacheKey,
     message: "Write requirement analysis report.",

package/src/orchestrate/interface/histories/transformInterfaceAssetHistories.ts

@@ -29,7 +29,7 @@ export const transformInterfaceAssetHistories = (
 
         ## User Request
 
-        ${analyze.reason}
+        ${analyze.instruction}
 
         ## Requirement Analysis Report
 
@@ -64,6 +64,7 @@ export const transformInterfaceAssetHistories = (
         \`\`\`
 
         ## Entity Relationship Diagrams
+        
         \`\`\`json
         ${JSON.stringify(
           (prisma.compiled as IAutoBePrismaCompileResult.ISuccess).diagrams,

package/src/orchestrate/interface/histories/transformInterfaceAuthorizationsHistories.ts

@@ -7,13 +7,14 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceAuthorizationsHistories = (
-  state: AutoBeState,
-  role: AutoBeAnalyzeRole,
-): Array<
+export const transformInterfaceAuthorizationsHistories = (props: {
+  state: AutoBeState;
+  role: AutoBeAnalyzeRole;
+  instruction: string;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => {
-  const analyze: AutoBeAnalyzeHistory = state.analyze!;
+  const analyze: AutoBeAnalyzeHistory = props.state.analyze!;
   return [
     {
       type: "systemMessage",
@@ -21,7 +22,7 @@ export const transformInterfaceAuthorizationsHistories = (
       created_at: new Date().toISOString(),
       text: AutoBeSystemPromptConstant.INTERFACE_AUTHORIZATION,
     },
-    ...transformInterfaceAssetHistories(state),
+    ...transformInterfaceAssetHistories(props.state),
     {
       type: "systemMessage",
       id: v7(),
@@ -44,14 +45,27 @@ export const transformInterfaceAuthorizationsHistories = (
       id: v7(),
       created_at: new Date().toISOString(),
       text: StringUtil.trim`
-        You have to make API operations for the given role:
+        ## API Design Instructions
+
+        The following API-specific instructions were extracted by AI from
+        the user's utterances. These focus ONLY on API interface design aspects
+        such as endpoint patterns, request/response formats, DTO schemas,
+        and operation specifications.
+
+        Apply these instructions when designing authorization-related API operations
+        for the ${props.role.name} role. Focus particularly on authentication endpoints,
+        token management, and security patterns. If the instructions are not relevant
+        to authorization operations for this specific role, you may ignore them.
+
+        ${props.instruction}
 
         ## Role
+        
+        You have to make API operations for the given role:
 
         \`\`\`json
-        ${JSON.stringify(role)}
+        ${JSON.stringify(props.role)}
         \`\`\`
-
       `,
     },
   ];

package/src/orchestrate/interface/histories/transformInterfaceComplementHistories.ts

@@ -7,11 +7,12 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceComplementHistories = (
-  state: AutoBeState,
-  document: AutoBeOpenApi.IDocument,
-  missed: string[],
-): Array<
+export const transformInterfaceComplementHistories = (props: {
+  state: AutoBeState;
+  instruction: string;
+  missed: string[];
+  document: AutoBeOpenApi.IDocument;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => [
   {
@@ -20,7 +21,7 @@ export const transformInterfaceComplementHistories = (
     created_at: new Date().toISOString(),
     text: AutoBeSystemPromptConstant.INTERFACE_OPERATION,
   },
-  ...transformInterfaceAssetHistories(state),
+  ...transformInterfaceAssetHistories(props.state),
   {
     type: "systemMessage",
     id: v7(),
@@ -38,33 +39,41 @@ export const transformInterfaceComplementHistories = (
     id: v7(),
     created_at: new Date().toISOString(),
     text: StringUtil.trim`
+      ## API Design Instructions
+
+      The following API-specific instructions were extracted by AI from
+      the user's utterances. These focus ONLY on API interface design aspects
+      such as endpoint patterns, request/response formats, DTO schemas,
+      and operation specifications.
+
+      Apply these instructions when completing the missing schema types.
+      Focus on ensuring the schemas align with the overall API design patterns
+      and data structure requirements. If the instructions are not relevant
+      to the specific schemas you need to create, you may ignore them.
+
+      ${props.instruction}
+
+      ## Operations
+
       Here is the OpenAPI operations what you AI have made:
 
       \`\`\`json
-      ${JSON.stringify(document.operations)}
+      ${JSON.stringify(props.document.operations)}
       \`\`\`
-    `,
-  },
-  {
-    type: "assistantMessage",
-    id: v7(),
-    created_at: new Date().toISOString(),
-    text: StringUtil.trim`
+
+      ## Schemas
+
       Here is the OpenAPI schemas what you AI have made:
 
       \`\`\`json
-      ${JSON.stringify(document.components.schemas)}
+      ${JSON.stringify(props.document.components.schemas)}
       \`\`\`
-    `,
-  },
-  {
-    type: "assistantMessage",
-    id: v7(),
-    created_at: new Date().toISOString(),
-    text: StringUtil.trim`
-      You AI have missed below schema types:
 
-      ${missed.map((s) => `- ${s}`).join("\n")}
+      ## Missed Types
+
+      However, you AI have missed below schema types:
+
+      ${props.missed.map((s) => `- ${s}`).join("\n")}
     `,
   },
 ];

package/src/orchestrate/interface/histories/transformInterfaceEndpointHistories.ts

@@ -8,11 +8,12 @@ import { AutoBeSystemPromptConstant } from "../../../constants/AutoBeSystemPromp
 import { AutoBeState } from "../../../context/AutoBeState";
 import { transformInterfaceAssetHistories } from "./transformInterfaceAssetHistories";
 
-export const transformInterfaceEndpointHistories = (
-  state: AutoBeState,
-  group: AutoBeInterfaceGroup,
-  authorizations: AutoBeOpenApi.IOperation[],
-): Array<
+export const transformInterfaceEndpointHistories = (props: {
+  state: AutoBeState;
+  group: AutoBeInterfaceGroup;
+  authorizations: AutoBeOpenApi.IOperation[];
+  instruction: string;
+}): Array<
   IAgenticaHistoryJson.IAssistantMessage | IAgenticaHistoryJson.ISystemMessage
 > => [
   {
@@ -21,25 +22,41 @@ export const transformInterfaceEndpointHistories = (
     created_at: new Date().toISOString(),
     text: AutoBeSystemPromptConstant.INTERFACE_ENDPOINT,
   },
-  ...transformInterfaceAssetHistories(state),
+  ...transformInterfaceAssetHistories(props.state),
   {
     type: "assistantMessage",
     id: v7(),
     created_at: new Date().toISOString(),
     text: StringUtil.trim`
+      ## API Design Instructions
+
+      The following API-specific instructions were extracted by AI from
+      the user's utterances. These focus ONLY on API interface design aspects
+      such as endpoint patterns, request/response formats, DTO schemas,
+      and operation specifications.
+
+      Apply these instructions when designing endpoints for the ${props.group.name} group.
+      Consider the specified URL patterns, HTTP methods, parameter structures,
+      and response formats. If the instructions are not relevant to this specific
+      endpoint group, you may ignore them.
+
+      ${props.instruction}
+
+      ## Group Information
+
       Here is the target group for the endpoints:
 
       \`\`\`json
-      ${JSON.stringify(group)}
+      ${JSON.stringify(props.group)}
       \`\`\`
 
-      **IMPORTANT: DO NOT DUPLICATE EXISTING OPERATIONS**
+      ## Already Existing Operations
 
       These operations already exist. Do NOT create similar endpoints:
 
       \`\`\`json
       ${JSON.stringify(
-        authorizations.map((op) => ({
+        props.authorizations.map((op) => ({
           path: op.path,
           method: op.method,
           name: op.name,