@minded-ai/mindedjs 3.1.21 → 3.1.23

package/docs/low-code-editor/tools.md

@@ -7,10 +7,16 @@ Tools are reusable functions that agents can call to perform specific actions li
 Every tool must implement the `Tool` interface:
 
 ```ts
-interface Tool<Input extends z.ZodSchema, Memory> {
+// Example: Tool with input and optional output schemas
+interface Tool<
+  Input extends z.ZodSchema,
+  Memory = any,
+  Output extends z.ZodSchema = z.ZodTypeAny
+> {
   name: string; // Unique tool identifier
   description: string; // What the tool does (used by LLM)
   input: Input; // Zod schema for input validation
+  output?: Output; // Optional: Zod schema for output validation (e.g., outputSchema)
   isGlobal?: boolean; // Optional: available across all LLM calls
   execute: ({ input, state, agent }) => Promise<{ result? }>;
 }
@@ -140,6 +146,85 @@ const updateOrderSchema = z.object({
 });
 ```
 
+## Output Schema Configuration
+
+Tools can optionally define an output schema to validate and structure their return values. This provides type safety and clear documentation of what the tool returns.
+
+### Defining Output Schema
+
+**Important**: The output schema variable must be named `outputSchema` for the platform to parse it correctly.
+
+```ts
+import { z } from 'zod';
+import { Tool } from '@minded-ai/mindedjs';
+import memorySchema from '../schema';
+
+type Memory = z.infer<typeof memorySchema>;
+
+const inputSchema = z.object({
+  email: z.string().describe('User email address'),
+  password: z.string().describe('User password'),
+});
+
+// Must be named 'outputSchema'
+const outputSchema = z.object({
+  success: z.boolean().describe('Status of the login operation'),
+  message: z.string().describe('Login status message'),
+  url: z.string().describe('Dashboard URL after successful login'),
+  usedPersistedSession: z.boolean().describe('Whether a persisted session was used'),
+});
+
+const loginTool: Tool<typeof inputSchema, Memory, typeof outputSchema> = {
+  name: 'login_to_dashboard',
+  description: 'Login to dashboard and return access details',
+  input: inputSchema,
+  output: outputSchema,
+  type: 'rpa',
+  execute: async ({ input, state, agent, page }): Promise<{ result: z.infer<typeof outputSchema> }> => {
+    // Tool logic here
+    const loginResult = await performLogin(page, input.email, input.password);
+
+    return {
+      result: {
+        success: true,
+        message: 'Successfully logged in',
+        url: page.url(),
+        usedPersistedSession: false,
+      },
+    };
+  },
+};
+
+export default loginTool;
+```
+
+### Benefits of Output Schema
+
+- **Type Safety**: TypeScript will enforce that your return value matches the output schema
+- **Validation**: Zod validates the output at runtime to catch bugs early
+- **Documentation**: Output schema serves as clear documentation of what the tool returns
+- **LLM Context**: The LLM receives structured information about the tool's output format
+
+### Output Schema vs Result
+
+- **Without output schema**: Return any value in `result`, no validation
+- **With output schema**: Return value must match the schema structure
+
+```ts
+// Without output schema - any result
+return { result: 'Login successful' };
+
+// With output schema - typed and validated
+return {
+  result: {
+    success: true,
+    message: 'Login successful',
+    url: 'https://dashboard.example.com',
+    usedPersistedSession: false,
+  },
+};
+```
+
 ## Tool Registration
 
 ### Global Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "3.1.21",
+  "version": "3.1.23",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agent.ts

@@ -1276,11 +1276,6 @@ export class Agent {
 
       const { toolName, params, flags } = parseDirectToolExecutionArgs(toolArgs);
 
-      // Set environment variable for cookies flag so browser session can read it
-      if (flags.noCookies) {
-        process.env.MINDED_NO_COOKIES = 'true';
-      }
-
       logger.info({
         message: '[runTool] Executing tool',
         toolName,

package/src/browserTask/executeBrowserTask.ts

@@ -17,7 +17,6 @@ import { BrowserTaskMode, InvokeBrowserTaskOptions } from './types';
 import { isLocalOperatorSetup, validateLocalOperatorSetup } from '../cli/localOperatorSetup';
 import { getConfig } from '../platform/config';
 import CDP from 'chrome-remote-interface';
-import { CookieStore } from './CookieStore';
 import { ProxyType } from '../types/Tools.types';
 
 // Map to track sessionId to instanceId for local browser sessions
@@ -26,9 +25,6 @@ const localSessionInstances = new Map<string, string>();
 // Map to track CDP clients for cookie management
 const cdpClients = new Map<string, CDP.Client>();
 
-// Initialize cookie store
-const cookieStore = new CookieStore(path.join(process.cwd(), 'local_storage', 'cookies'));
-
 // Helper function to extract port from CDP URL
 const extractPortFromCdpUrl = (cdpUrl: string): number | null => {
   try {
@@ -39,61 +35,6 @@ const extractPortFromCdpUrl = (cdpUrl: string): number | null => {
   }
 };
 
-// Helper function to load cookies for a session
-const loadCookiesForSession = async (sessionId: string): Promise<void> => {
-  // Check if cookies should be disabled
-  const noCookies = process.env.MINDED_NO_COOKIES === 'true';
-  if (noCookies) {
-    logger.info({ message: '[Browser] Cookies disabled via cookies=false flag', sessionId });
-    return;
-  }
-
-  const stored = await cookieStore.load();
-  if (!stored || stored.length === 0) {
-    logger.info({ message: '[Browser] No stored cookies to load', sessionId });
-    return;
-  }
-  const cdp = cdpClients.get(sessionId);
-  if (!cdp) {
-    logger.warn({ message: '[Browser] No CDP client found for session', sessionId });
-    return;
-  }
-
-  try {
-    await cdp.Network.setCookies({ cookies: stored });
-    logger.info({ message: '[Browser] Loaded cookies into browser session', sessionId, count: stored.length });
-  } catch (error) {
-    logger.warn({ message: '[Browser] Failed to set cookies via CDP', sessionId, error });
-  }
-};
-
-// Helper function to save cookies for a session
-const saveCookiesForSession = async (sessionId: string): Promise<void> => {
-  // Check if cookies should be disabled
-  const noCookies = process.env.MINDED_NO_COOKIES === 'true';
-  if (noCookies) {
-    return;
-  }
-
-  try {
-    const cdp = cdpClients.get(sessionId);
-    if (!cdp) {
-      logger.warn({ message: '[Browser] No CDP client found for session', sessionId });
-      return;
-    }
-
-    const result = await cdp.Network.getAllCookies();
-    if (result) {
-      await cookieStore.save(result.cookies);
-      logger.info({ message: '[Browser] Saved cookies from browser session', sessionId, count: result.cookies.length });
-    } else {
-      logger.warn({ message: '[Browser] No cookies found in browser session', sessionId });
-    }
-  } catch (error) {
-    logger.warn({ message: '[Browser] Failed to get/save cookies from session', sessionId, error: JSON.stringify(error) });
-  }
-};
-
 // Helper function to cleanup CDP client
 const cleanupCdpClient = async (sessionId: string): Promise<void> => {
   const cdp = cdpClients.get(sessionId);
@@ -144,13 +85,6 @@ export const createBrowserSession = async ({
       logger.info({ message: '[Browser] Created CDP client for session', sessionId, port });
     }
 
-    // Load cookies for this session (best-effort)
-    try {
-      await loadCookiesForSession(sessionId);
-    } catch (error) {
-      logger.warn({ message: '[Browser] Failed to load cookies for session', sessionId, error });
-    }
-
     return {
       sessionId,
       cdpUrl,
@@ -213,6 +147,7 @@ export const destroyBrowserSession = async ({
     };
   }
 
+  // Destroy browser sessions via socket for both cloud and on-prem
   const response = await mindedConnection.awaitEmit<DestroyBrowserSessionRequest, DestroyBrowserSessionResponse>(
     mindedConnectionSocketMessageType.DESTROY_BROWSER_SESSION,
     {
@@ -345,13 +280,6 @@ export const invokeBrowserTask = async (options: InvokeBrowserTaskOptions): Prom
           }
         }
 
-        // Save cookies after task completes (best-effort)
-        try {
-          await saveCookiesForSession(sessionId);
-        } catch (error) {
-          logger.warn({ message: '[Browser] Failed to save cookies after task completion', sessionId, error });
-        }
-
         return {
           result,
           steps: [],

package/src/cli/validateAgent.ts

@@ -480,6 +480,23 @@ export async function runValidateCommand(agentPath?: string): Promise<void> {
     process.exit(1);
   }
 
+  // Check if mainFlow.yaml exists in any of the flows folders
+  let mainFlowFound = false;
+  for (const folder of flowsFolders) {
+    const resolvedFolder = path.isAbsolute(folder) ? folder : path.join(projectDir, folder);
+    const mainFlowPath = path.join(resolvedFolder, 'mainFlow.yaml');
+    if (fs.existsSync(mainFlowPath)) {
+      mainFlowFound = true;
+      break;
+    }
+  }
+
+  if (!mainFlowFound) {
+    console.error('Error: mainFlow.yaml not found in any configured flows folder');
+    console.error('The flows directory must contain a mainFlow.yaml file');
+    process.exit(1);
+  }
+
   console.log(`\nValidating ${flowFiles.length} flow(s)...\n`);
 
   const graphCompilationErrors: string[] = [];

package/src/nodes/addPromptNode.ts

@@ -84,6 +84,7 @@ export const addPromptNode = async ({ graph, node, llm, tools, emit, agent }: Ad
                 browserTaskMode,
                 toolCallId,
                 toolName: tool.name,
+                persistSession: tool.persistSession,
               },
               async (page) => {
                 // Pass page directly to RPA tool execution

package/src/nodes/addToolRunNode.ts

@@ -53,6 +53,7 @@ export const addToolRunNode = async ({ graph, tools, toolNode, attachedToNodeNam
               proxyUser: matchedTool.proxyUser,
               proxyPass: matchedTool.proxyPass,
               toolName: matchedTool.name,
+              persistSession: matchedTool.persistSession,
             },
             async (page) => {
               // Pass page directly to RPA tool execution

package/src/platform/toolExecutor.ts

@@ -99,6 +99,7 @@ export class ToolExecutor {
             proxyCountryCode: tool.proxyCountryCode,
             proxyType: tool.proxyType,
             toolName,
+            persistSession: tool.persistSession,
           },
           async (page) => {
             // Pass page directly to RPA tool execution

package/src/toolsLibrary/browserSessionPersistence.ts

@@ -0,0 +1,203 @@
+import { BrowserContext, Page } from 'playwright';
+import { logger } from '../utils/logger';
+import { saveRecord, getRecords } from './storage';
+
+const BROWSER_SESSION_KEY = 'browser-session';
+
+interface Cookie {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+interface LocalStorageEntry {
+  url: string;
+  data: Record<string, string>;
+}
+
+/**
+ * Extract localStorage from the current page
+ */
+const extractLocalStorageFromPage = async (page: Page): Promise<Record<string, string>> => {
+  return await page.evaluate(() => Object.fromEntries(Object.entries(localStorage)));
+};
+
+/**
+ * Fetch both cookies and localStorage
+ */
+export const fetchSessionDataViaSocket = async (): Promise<{
+  cookies: Cookie[] | null;
+  localStorage: LocalStorageEntry[] | null;
+}> => {
+  try {
+    const records = await getRecords({
+      filters: { key: BROWSER_SESSION_KEY },
+    });
+
+    if (records.length === 0) {
+      return { cookies: null, localStorage: null };
+    }
+
+    // Take the last (most recent) record
+    const latestRecord = records[0];
+    const cookies = latestRecord.data?.cookies || null;
+    const localStorage = latestRecord.data?.localStorage || null;
+
+    return { cookies, localStorage };
+  } catch (error) {
+    logger.warn({ message: 'Failed to fetch session data', error });
+    return { cookies: null, localStorage: null };
+  }
+};
+
+/**
+ * Save both cookies and localStorage for ALL origins
+ */
+export const saveSessionDataViaSocket = async (
+  context: BrowserContext,
+  page: Page,
+  sessionId: string,
+): Promise<void> => {
+  try {
+    const cookies = await context.cookies();
+    const data: Record<string, unknown> = {};
+
+    if (cookies && cookies.length > 0) {
+      data.cookies = cookies;
+    }
+
+    // Extract localStorage for ALL origins using CDP
+    let client;
+    try {
+      client = await context.newCDPSession(page);
+
+      // Enable Target domain to track all frames and their origins
+      await client.send('Target.setDiscoverTargets', { discover: true });
+
+      // Get all targets (frames, workers, etc.)
+      type TargetInfo = {
+        targetId: string;
+        type: string;
+        title: string;
+        url: string;
+        attached: boolean;
+      };
+
+      const response = await client.send('Target.getTargets');
+      const targetInfos = (response as { targetInfos: TargetInfo[] }).targetInfos;
+
+      // Extract unique origins from all page-type targets
+      const origins = new Set<string>();
+      for (const target of targetInfos || []) {
+        if (target.type === 'page' || target.type === 'iframe') {
+          try {
+            const url = new URL(target.url);
+            if (url.protocol === 'http:' || url.protocol === 'https:') {
+              origins.add(url.origin);
+            }
+          } catch {
+            // Ignore invalid URLs
+          }
+        }
+      }
+
+      // Also add the current page origin
+      try {
+        const currentOrigin = new URL(page.url()).origin;
+        origins.add(currentOrigin);
+      } catch {
+        // Ignore if current URL is invalid
+      }
+
+      // Extract localStorage from all origins in parallel
+      const extractionPromises = Array.from(origins).map(async (origin) => {
+        try {
+          type DOMStorageResponse = {
+            entries: Array<[string, string]>;
+          };
+
+          const storageResponse = await client!.send('DOMStorage.getDOMStorageItems', {
+            storageId: {
+              securityOrigin: origin,
+              isLocalStorage: true,
+            },
+          });
+          const { entries } = storageResponse as DOMStorageResponse;
+
+          if (entries && entries.length > 0) {
+            const data = Object.fromEntries(entries);
+
+            // Check payload size to prevent WebSocket errors (10MB limit as safety margin)
+            const dataSize = JSON.stringify(data).length;
+            if (dataSize > 10 * 1024 * 1024) {
+              logger.warn({
+                message: 'localStorage data too large, skipping origin',
+                origin,
+                sizeMB: (dataSize / 1024 / 1024).toFixed(2)
+              });
+              return null;
+            }
+
+            return {
+              url: origin,
+              data,
+            };
+          }
+        } catch (err) {
+          logger.warn({ message: 'Failed to extract localStorage for origin', origin, error: err });
+        }
+        return null;
+      });
+
+      const results = await Promise.all(extractionPromises);
+      const localStorageByOrigin = results.filter(Boolean) as LocalStorageEntry[];
+
+      if (localStorageByOrigin.length > 0) {
+        data.localStorage = localStorageByOrigin;
+      }
+    } catch (err) {
+      // Fallback: If CDP approach fails, use current page only
+      logger.warn({ message: 'Failed to extract localStorage via CDP, falling back to current page', error: err });
+      try {
+        const currentUrl = page.url();
+        const localStorageData = await extractLocalStorageFromPage(page);
+
+        if (Object.keys(localStorageData).length > 0) {
+          data.localStorage = [{
+            url: currentUrl,
+            data: localStorageData
+          }];
+        }
+      } catch (fallbackErr) {
+        logger.warn({ message: 'Failed to extract localStorage via fallback method', error: fallbackErr });
+      }
+    } finally {
+      if (client) {
+        await client.detach().catch(() => { });
+      }
+    }
+
+    if (Object.keys(data).length === 0) {
+      return;
+    }
+
+    // Add key to data for filtering
+    data.key = BROWSER_SESSION_KEY;
+
+    // Save with the actual sessionId, not a constant key
+    // TTL: 10 days (in seconds)
+    const TTL_10_DAYS = 10 * 24 * 60 * 60;
+    try {
+      await saveRecord(sessionId, data, TTL_10_DAYS);
+    } catch (error) {
+      logger.warn({ message: 'Failed to save session data', sessionId, error });
+    }
+  } catch (error) {
+    logger.warn({ message: 'Failed to save session data', sessionId, error });
+  }
+};