Empty PR 6 (#295)

* Empty PR 6 - minimal change for testing purposes

Co-Authored-By: srith@agentuity.com <rithsenghorn@gmail.com>

* add tutorial APIs

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: srith@agentuity.com <rithsenghorn@gmail.com>
Co-authored-by: afterrburn <sun_rsh@outlook.com>

Author: 3 people

agent-docs/src/agents/agent-pulse/index.ts

@@ -73,7 +73,7 @@ function buildCurrentTutorialInfo(
  */
 function defaultFallbackContext(): string {
 	return `===AVAILABLE TUTORIALS====
-Unable to load tutorial list. Please try again later or contact support.`;
+Unable to load tutorial list currently`;
 }
 
 export default async function Agent(

agent-docs/src/agents/agent-pulse/request/parser.ts

@@ -15,10 +15,8 @@ export function parseAgentRequest(
 			const body = jsonData as any;
 			message = body.message || "";
 			useDirectLLM = body.use_direct_llm || false;
-			// Process conversation history
 			if (Array.isArray(body.conversationHistory)) {
 				conversationHistory = body.conversationHistory.map((msg: any) => {
-					// Extract only role and content
 					return {
 						role: msg.role || (msg.author ? msg.author.toUpperCase() : "USER"),
 						content: msg.content || "",
@@ -28,7 +26,6 @@ export function parseAgentRequest(
 
 			tutorialData = body.tutorialData || undefined;
 		} else {
-			// Fallback for non-object data
 			message = String(jsonData || "");
 		}
 

agent-docs/src/agents/agent-pulse/state/manager.ts

@@ -30,15 +30,21 @@ export async function handleTutorialState(
               totalSteps: action.totalSteps,
               currentStep: action.currentStep,
               tutorialStep: {
-                title: (tutorialStep.data.meta?.title as string) || tutorialStep.data.slug,
-                mdx: tutorialStep.data.mdx,
-                snippets: tutorialStep.data.snippets,
-                totalSteps: action.totalSteps
+                title: tutorialStep.data.tutorialStep.title,
+                mdx: tutorialStep.data.tutorialStep.mdx,
+                snippets: tutorialStep.data.tutorialStep.snippets,
+                totalSteps: tutorialStep.data.tutorialStep.totalSteps
               }
             };
             state.clearAction();
             ctx.logger.info("Tutorial state processed successfully");
             return tutorialData;
+          } else {
+            // Handle API errors gracefully
+            ctx.logger.error("Failed to fetch tutorial step: %s", tutorialStep.error || 'Unknown error');
+            if (tutorialStep.details) {
+              ctx.logger.error("Error details: %s", JSON.stringify(tutorialStep.details));
+            }
           }
         }
         break;

agent-docs/src/agents/agent-pulse/tools.ts

@@ -24,7 +24,7 @@ export async function createTools(context: ToolContext) {
      * Tool for starting a tutorial - adds action to state queue
      */
     const startTutorialAtStep = tool({
-        description: "Start a specific tutorial for the user. You must call this function in order for the user to see the tutorial step content. The step number should be between 1 and the total number of steps in the tutorial.",
+        description: "Start a specific tutorial for the user. You must call this function in order for the user to see the tutorial step content. The tutorial content will be injected to the final response automatically -- you do not have to narrate the tutorial content. The step number should be between 1 and the total number of steps in the tutorial.",
         parameters: z.object({
             tutorialId: z.string().describe("The exact ID of the tutorial to start"),
             stepNumber: z.number().describe("The step number of the tutorial to start (1 to total available steps in the tutorial)")
@@ -53,7 +53,7 @@ export async function createTools(context: ToolContext) {
     });
 
     /**
-     * Tool for talking to other agents (nong-tutorial functionality)
+     * Tool that talks to docs agent.
      * This tool doesn't use state - it returns data directly
      */
     const askDocsAgentTool = tool({
@@ -71,28 +71,12 @@ export async function createTools(context: ToolContext) {
                 data: agentPayload,
                 contentType: 'application/json'
             })
-             // TODO: handle the docs referencing and inject it to the frontend response
+            // TODO: handle the docs referencing and inject it to the frontend response
             const responseData = await response.data.json();
             return responseData;
         },
     });
 
-    /**
-     * TODO: This tool allow the agent to get details information about the code execution that the user performed.
-     */
-    const fetchCodeExecutionResultTool = tool({
-        description: "Fetch code execution results from the frontend",
-        parameters: z.object({
-            executionId: z.string().describe("The ID of the code execution"),
-        }),
-        execute: async ({ executionId }) => {
-            agentContext.logger.info("Fetching execution result for: %s", executionId);
-            // This would actually fetch execution results
-            // For now, just return a mock response
-            return `Result for execution ${executionId}: console.log('Hello, World!');\n// Output: Hello, World!`;
-        },
-    });
-
     // Return tools object
     return {
         startTutorialById: startTutorialAtStep,

agent-docs/src/agents/agent-pulse/tutorial.ts

@@ -7,12 +7,15 @@ export interface Tutorial {
   title: string;
   description: string;
   totalSteps: number;
+  difficulty?: string;
+  estimatedTime?: string;
 }
 
 interface ApiResponse<T> {
   success: boolean;
   data?: T;
   error?: string;
+  details?: any;
   status?: number;
 }
 
@@ -27,21 +30,30 @@ export interface TutorialSnippet {
 
 interface TutorialStepResponseData {
   tutorialId: string;
-  stepNumber: number;
-  slug: string;
-  meta: Record<string, unknown>;
-  mdx: string;
-  snippets: TutorialSnippet[];
+  totalSteps: number;
+  currentStep: number;
+  tutorialStep: {
+    title: string;
+    mdx: string;
+    snippets: TutorialSnippet[];
+    totalSteps: number;
+    estimatedTime?: string;
+  };
 }
 
 export async function getTutorialList(ctx: AgentContext): Promise<ApiResponse<Tutorial[]>> {
   try {
     const response = await fetch(`${TUTORIAL_API_BASE_URL}/api/tutorials`);
 
     if (!response.ok) {
-      const error = await response.json();
-      ctx.logger.error('Tutorial API error: %s', error);
-      throw new Error(`Tutorial API error: ${JSON.stringify(error)}`);
+      const errorData = await response.json().catch(() => ({ error: response.statusText })) as { error?: string; details?: any };
+      ctx.logger.error('Tutorial API error: %s', JSON.stringify(errorData));
+      return {
+        success: false,
+        status: response.status,
+        error: errorData.error || response.statusText,
+        details: errorData.details
+      };
     }
 
     const tutorials = await response.json() as Tutorial[];
@@ -53,28 +65,66 @@ export async function getTutorialList(ctx: AgentContext): Promise<ApiResponse<Tu
     };
   } catch (error) {
     ctx.logger.error('Error fetching tutorial list: %s', error);
-    throw error;
+    return {
+      success: false,
+      error: `Network error: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
 }
 
 export async function getTutorialMeta(tutorialId: string, ctx: AgentContext): Promise<ApiResponse<Tutorial>> {
   try {
-    // New behavior: fetch all, then find by id
-    const response = await fetch(`${TUTORIAL_API_BASE_URL}/api/tutorials`);
+    const response = await fetch(`${TUTORIAL_API_BASE_URL}/api/tutorials/${tutorialId}`);
+    
     if (!response.ok) {
-      const error = `Failed to fetch tutorial list: ${response.statusText}`;
-      ctx.logger.error(error);
-      return { success: false, status: response.status, error: response.statusText };
+      const errorData = await response.json().catch(() => ({ error: response.statusText })) as { error?: string; details?: any };
+      ctx.logger.error('Failed to fetch tutorial %s: %s', tutorialId, JSON.stringify(errorData));
+      return {
+        success: false,
+        status: response.status,
+        error: errorData.error || response.statusText,
+        details: errorData.details
+      };
     }
-    const tutorials = (await response.json()) as Tutorial[];
-    const found = tutorials.find(t => t.id === tutorialId);
-    if (!found) {
-      return { success: false, status: 404, error: 'Tutorial not found' };
+
+    const responseData = await response.json() as ApiResponse<{
+      id: string;
+      metadata: {
+        title: string;
+        description: string;
+        totalSteps: number;
+        difficulty?: string;
+        estimatedTime?: string;
+      };
+      fullContent: string;
+      steps: Array<{ stepNumber: number; title: string; estimatedTime?: string; }>;
+    }>;
+    
+    if (!responseData.success || !responseData.data) {
+      return {
+        success: false,
+        error: responseData.error || 'Invalid response format'
+      };
     }
-    return { success: true, data: found };
+
+    // Convert to Tutorial format for backward compatibility
+    const tutorial: Tutorial = {
+      id: responseData.data.id,
+      title: responseData.data.metadata.title,
+      description: responseData.data.metadata.description,
+      totalSteps: responseData.data.metadata.totalSteps,
+      difficulty: responseData.data.metadata.difficulty,
+      estimatedTime: responseData.data.metadata.estimatedTime
+    };
+
+    ctx.logger.info('Fetched tutorial metadata for %s', tutorialId);
+    return { success: true, data: tutorial };
   } catch (error) {
     ctx.logger.error('Error fetching tutorial metadata for %s: %s', tutorialId, error);
-    throw error;
+    return {
+      success: false,
+      error: `Network error: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
 }
 
@@ -83,16 +133,32 @@ export async function getTutorialStep(tutorialId: string, stepNumber: number, ct
     const response = await fetch(`${TUTORIAL_API_BASE_URL}/api/tutorials/${tutorialId}/steps/${stepNumber}`);
 
     if (!response.ok) {
-      ctx.logger.error('Failed to fetch tutorial step %d for tutorial %s: %s', stepNumber, tutorialId, response.statusText);
-      return { success: false, status: response.status, error: response.statusText };
+      const errorData = await response.json().catch(() => ({ error: response.statusText })) as { error?: string; details?: any };
+      ctx.logger.error('Failed to fetch tutorial step %d for tutorial %s: %s', stepNumber, tutorialId, JSON.stringify(errorData));
+      return {
+        success: false,
+        status: response.status,
+        error: errorData.error || response.statusText,
+        details: errorData.details
+      };
     }
 
-    const responseData = await response.json();
-    ctx.logger.info('Fetched step %d for tutorial %s', stepNumber, tutorialId);
+    const responseData = await response.json() as ApiResponse<TutorialStepResponseData>;
+    
+    if (!responseData.success || !responseData.data) {
+      return {
+        success: false,
+        error: responseData.error || 'Invalid response format'
+      };
+    }
 
-    return responseData as ApiResponse<TutorialStepResponseData>;
+    ctx.logger.info('Fetched step %d for tutorial %s', stepNumber, tutorialId);
+    return responseData;
   } catch (error) {
     ctx.logger.error('Error fetching tutorial step %d for tutorial %s: %s', stepNumber, tutorialId, error);
-    throw error;
+    return {
+      success: false,
+      error: `Network error: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
 }

app/(docs)/[[...slug]]/page.tsx

@@ -20,6 +20,7 @@ import { CommunityButton } from '../../../components/Community';
 import CopyPageDropdown from '../../../components/CopyPageDropdown';
 import { NavButton } from '../../../components/NavButton';
 import CodeFromFiles from '../../../components/CodeFromFiles';
+import TutorialStep from '../../../components/TutorialStep';
 
 
 export default async function Page(props: {
@@ -67,6 +68,7 @@ export default async function Page(props: {
 						Tab,
 						Tabs,
 						ThemeImage,
+						TutorialStep,
 						TypingAnimation,
 					}}
 				/>

app/api/tutorials/[id]/route.ts

@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { join } from 'path';
+import { parseTutorialMDXCached } from '@/lib/tutorial/mdx-parser';
+import { TutorialIdParamsSchema } from '@/lib/tutorial/schemas';
+
+interface RouteParams {
+  params: Promise<{ id: string }>;
+}
+
+export async function GET(request: NextRequest, { params }: RouteParams) {
+  try {
+    const rawParams = await params;
+    
+    // Validate parameters with Zod
+    const validationResult = TutorialIdParamsSchema.safeParse(rawParams);
+    if (!validationResult.success) {
+      return NextResponse.json(
+        { success: false, error: 'Invalid parameters', details: validationResult.error.format() },
+        { status: 400 }
+      );
+    }
+    
+    const { id } = validationResult.data;
+    const filePath = join(process.cwd(), 'content', 'Tutorial', `${id}.mdx`);
+    
+    const parsed = await parseTutorialMDXCached(filePath);
+    
+    return NextResponse.json({
+      success: true,
+      data: {
+        id,
+        metadata: parsed.metadata,
+        fullContent: parsed.fullContent,
+        steps: parsed.steps.map(step => ({
+          stepNumber: step.stepNumber,
+          title: step.title,
+          estimatedTime: step.estimatedTime,
+        }))
+      }
+    });
+  } catch (error) {
+    console.error(`Failed to load tutorial:`, error);
+    return NextResponse.json(
+      { success: false, error: 'Tutorial not found' },
+      { status: 404 }
+    );
+  }
+}

app/api/tutorials/[id]/steps/[stepNumber]/route.ts

@@ -0,0 +1,58 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { join } from 'path';
+import { parseTutorialMDXCached } from '@/lib/tutorial/mdx-parser';
+import { StepParamsSchema } from '@/lib/tutorial/schemas';
+
+interface RouteParams {
+  params: Promise<{ id: string; stepNumber: string }>;
+}
+
+export async function GET(request: NextRequest, { params }: RouteParams) {
+  try {
+    const rawParams = await params;
+    
+    // Validate and transform parameters with Zod
+    const validationResult = StepParamsSchema.safeParse(rawParams);
+    if (!validationResult.success) {
+      return NextResponse.json(
+        { success: false, error: 'Invalid parameters', details: validationResult.error.format() },
+        { status: 400 }
+      );
+    }
+    
+    const { id, stepNumber: stepNum } = validationResult.data;
+    
+    const filePath = join(process.cwd(), 'content', 'Tutorial', `${id}.mdx`);
+    const parsed = await parseTutorialMDXCached(filePath);
+    
+    const step = parsed.steps.find(s => s.stepNumber === stepNum);
+    if (!step) {
+      return NextResponse.json(
+        { success: false, error: 'Step not found' },
+        { status: 404 }
+      );
+    }
+    
+    return NextResponse.json({
+      success: true,
+      data: {
+        tutorialId: id,
+        totalSteps: parsed.metadata.totalSteps,
+        currentStep: stepNum,
+        tutorialStep: {
+          title: step.title,
+          mdx: step.mdxContent,
+          snippets: step.snippets,
+          totalSteps: parsed.metadata.totalSteps,
+          estimatedTime: step.estimatedTime,
+        }
+      }
+    });
+  } catch (error) {
+    console.error(`Failed to load tutorial step:`, error);
+    return NextResponse.json(
+      { success: false, error: 'Failed to load step' },
+      { status: 500 }
+    );
+  }
+}