Implement proper ADK error handling using native error fields instead of sentinel strings

frontend/package.json

@@ -34,6 +34,7 @@
     "@tsconfig/node22": "^22.0.1",
     "@types/lodash": "^4.17.17",
     "@types/node": "^22.14.0",
+    "@types/showdown": "^2.0.6",
     "@vitejs/plugin-vue": "^5.2.3",
     "@vue/tsconfig": "^0.7.0",
     "npm-run-all2": "^7.0.2",

frontend/src/api/adk.ts

@@ -215,7 +215,7 @@ export const sseRequest = async (
  * @param response - The ADK API response to extract text from
  * @param onlyLast - If true, returns only the last text section; if false,
  *                  returns all text sections concatenated with newlines
- * @returns The extracted text as a string
+ * @returns The extracted text as a string, or throws an error if error response detected
 */
 export const extractADKText = (response: ADKResponse|undefined, onlyLast: boolean = true): string => {
   // if response is undefined, return an empty string
@@ -235,6 +235,42 @@ export const extractADKText = (response: ADKResponse|undefined, onlyLast: boolea
       return textParts.map(x => x.text).join("\n");
   })
 
+  // Check for structured error responses
+  const allText = textSections.join("\n");
+  if (allText.includes("MANUGEN_ERROR:")) {
+    const errorMatch = allText.match(/MANUGEN_ERROR:\s*(\{.*?\})/s);
+    if (errorMatch) {
+      try {
+        const errorData = JSON.parse(errorMatch[1]);
+        throw new ManugenError(
+          errorData.error_type || 'unknown_error',
+          errorData.message || 'An error occurred',
+          errorData.details || '',
+          errorData.suggestion || ''
+        );
+      } catch (e) {
+        if (e instanceof ManugenError) {
+          throw e;
+        }
+        // If JSON parsing fails, throw a generic error
+        throw new ManugenError(
+          'parse_error',
+          'Failed to parse error response',
+          'The server returned an error but it could not be parsed properly.',
+          'Please try again or contact support if the problem persists.'
+        );
+      }
+    } else {
+      // MANUGEN_ERROR found but no valid JSON match
+      throw new ManugenError(
+        'parse_error',
+        'Malformed error response detected',
+        'The server returned an error but it could not be parsed properly.',
+        'Please try again or contact support if the problem persists.'
+      );
+    }
+  }
+
   if (onlyLast) {
     // if onlyLast is true, return the last text section
     return textSections.length > 0 ? textSections[textSections.length - 1] : "";
@@ -244,3 +280,20 @@ export const extractADKText = (response: ADKResponse|undefined, onlyLast: boolea
     return textSections.join("\n");
   }
 }
+
+/**
+ * Custom error class for Manugen AI errors
+ */
+export class ManugenError extends Error {
+  public readonly errorType: string;
+  public readonly details: string;
+  public readonly suggestion: string;
+
+  constructor(errorType: string, message: string, details: string = '', suggestion: string = '') {
+    super(message);
+    this.name = 'ManugenError';
+    this.errorType = errorType;
+    this.details = details;
+    this.suggestion = suggestion;
+  }
+}

frontend/src/api/index.ts

@@ -21,7 +21,7 @@ export const request = async <Response>(
   if (!response.ok) error = "Response not OK";
 
   /** try to parse as json */
-  let parsed: Response;
+  let parsed: Response | undefined;
   try {
     parsed = await response.clone().json();
   } catch (e) {

frontend/src/pages/PageEditor.vue

@@ -142,8 +142,9 @@ import Portal from "./portal";
 import { agentsWorking } from "@/components/AppAgents.vue";
 import type { AgentId } from "@/api/agents";
 import {  aiWriter, aiWriterAsync } from "@/api/endpoints";
-import { type ADKSessionResponse, ensureSessionExists, extractADKText } from "@/api/adk";
+import { type ADKSessionResponse, ensureSessionExists, extractADKText, ManugenError } from "@/api/adk";
 import example from "./example.txt?raw";
+import { toast } from 'vue3-toastify';
 
 /** app info */
 const { VITE_TITLE: title } = import.meta.env;
@@ -170,7 +171,7 @@ onMounted(() => {
     adkUsername.value,
     adkSessionId.value
   ).then((data) => {
-    sessionData.value = data;
+    sessionData.value = data as ADKSessionResponse;
     console.log("ADK session created:", data);
   }).catch((error) => {
     console.error("Error creating ADK session:", error);
@@ -333,25 +334,87 @@ const action =
     /** tell agents component that these agents are working in this portal */
     agentsWorking.value[portalId] = agents;
 
-    /** run actual work func, providing context */
-    const result = await func(context);
-
-    /** tell agents component that work is done */
-    delete agentsWorking.value[portalId];
-
-    /** find node of portal created earlier */
-    const portalNode = findPortal(portalId);
-    if (!portalNode) return;
-
-    editor.value
-      .chain()
-      /** delete portal node */
-      .deleteRange({
-        from: portalNode.pos,
-        to: portalNode.pos + portalNode.node.nodeSize,
-      })
-      .insertContentAt(portalNode.pos,  paragraphizeToJSON(result))
-      .run();
+    try {
+      /** run actual work func, providing context */
+      const result = await func(context);
+
+      /** tell agents component that work is done */
+      delete agentsWorking.value[portalId];
+
+      /** find node of portal created earlier */
+      const portalNode = findPortal(portalId);
+      if (!portalNode) return;
+
+      editor.value
+        .chain()
+        /** delete portal node */
+        .deleteRange({
+          from: portalNode.pos,
+          to: portalNode.pos + portalNode.node.nodeSize,
+        })
+        .insertContentAt(portalNode.pos,  paragraphizeToJSON(result))
+        .run();
+    } catch (error) {
+      /** tell agents component that work is done */
+      delete agentsWorking.value[portalId];
+
+      /** find node of portal created earlier */
+      const portalNode = findPortal(portalId);
+      if (!portalNode) return;
+
+      // Handle ManugenError specially
+      if (error instanceof ManugenError) {
+        // Show a detailed error toast
+        toast.error(
+          `<strong>${error.message}</strong><br/>${error.suggestion ? `<em>Suggestion: ${error.suggestion}</em>` : ''}`,
+          {
+            position: "bottom-left",
+            autoClose: 10000,
+            hideProgressBar: false,
+            closeOnClick: true,
+            pauseOnHover: true,
+            dangerouslyHTMLString: true,
+          }
+        );
+
+        // Insert an error message in the editor instead of empty content
+        const errorText = `⚠️ Error: ${error.message}${error.suggestion ? `\n\nSuggestion: ${error.suggestion}` : ''}`;
+
+        editor.value
+          .chain()
+          /** delete portal node */
+          .deleteRange({
+            from: portalNode.pos,
+            to: portalNode.pos + portalNode.node.nodeSize,
+          })
+          .insertContentAt(portalNode.pos, paragraphizeToJSON(errorText))
+          .run();
+      } else {
+        // Handle generic errors
+        console.error('Unexpected error in action:', error);
+
+        toast.error(
+          'An unexpected error occurred. Please try again.',
+          {
+            position: "bottom-left",
+            autoClose: 5000,
+          }
+        );
+
+        // Insert a generic error message
+        const errorText = '⚠️ An unexpected error occurred. Please try again.';
+
+        editor.value
+          .chain()
+          /** delete portal node */
+          .deleteRange({
+            from: portalNode.pos,
+            to: portalNode.pos + portalNode.node.nodeSize,
+          })
+          .insertContentAt(portalNode.pos, paragraphizeToJSON(errorText))
+          .run();
+      }
+    }
   };
 
 const aiWriterSelectAction = (label: string, icon: any, prefix: string = "", agent: AgentId = "aiWriter") => {

packages/manugen-ai/src/manugen_ai/adk.py

@@ -1,14 +1,17 @@
+import json
 from abc import ABCMeta
 
 from google.adk.agents import BaseAgent
 from google.adk.agents.invocation_context import InvocationContext
 from google.adk.events import Event, EventActions
 from google.genai import types
 
+from .schema import ErrorResponse
+
 
 class ManugenAIBaseAgent(BaseAgent, metaclass=ABCMeta):
     """
-    TODO: add docs
+    Base agent class for Manugen AI with enhanced error handling.
     """
 
     def error_message(self, ctx: InvocationContext, error_msg: str) -> Event:
@@ -26,6 +29,45 @@ def error_message(self, ctx: InvocationContext, error_msg: str) -> Event:
             ),
         )
 
+    def structured_error_message(
+        self, 
+        ctx: InvocationContext, 
+        error_type: str,
+        message: str,
+        details: str = "",
+        suggestion: str = ""
+    ) -> Event:
+        """
+        Create a structured error response that the UI can parse and display properly.
+
+        Args:
+            ctx: The invocation context
+            error_type: Type of error (e.g., 'model_error', 'agent_error', 'validation_error')
+            message: Human-readable error message
+            details: Additional error details for debugging
+            suggestion: Suggested action for the user
+        """
+        error_response = ErrorResponse(
+            error_type=error_type,
+            message=message,
+            details=details,
+            suggestion=suggestion
+        )
+
+        # Create a structured JSON response that the frontend can parse
+        error_json = error_response.model_dump_json()
+
+        return Event(
+            author=self.name,
+            invocation_id=ctx.invocation_id,
+            content=types.Content(
+                role="model",
+                parts=[
+                    types.Part(text=f"MANUGEN_ERROR: {error_json}"),
+                ],
+            ),
+        )
+
     def get_transfer_to_agent_event(
         self, ctx: InvocationContext, agent: BaseAgent
     ) -> Event: