@minded-ai/mindedjs 1.0.0-ec2-beta-1

package/src/browserTask/types.ts

@@ -0,0 +1,37 @@
+export enum BrowserTaskMode {
+  ON_PREM = 'onPrem',
+  LOCAL = 'localRun',
+  CLOUD = 'cloud',
+}
+
+// Types used for invoking browser tasks
+export type BrowserTaskHook = { name: string };
+
+export type OutputSchemaField = {
+  name: string;
+  type: 'string' | 'number';
+  description?: string;
+  required?: boolean;
+};
+
+export type ToolSchema = {
+  name: string;
+  description?: string;
+  inputParams: Array<{
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description?: string;
+    required?: boolean;
+  }>;
+};
+
+export interface InvokeBrowserTaskOptions {
+  sessionId: string;
+  cdpUrl: string;
+  task: string;
+  keepAlive?: boolean;
+  hooks?: BrowserTaskHook[];
+  browserTaskMode: BrowserTaskMode;
+  toolSchemas?: ToolSchema[];
+  outputSchema?: OutputSchemaField[];
+}

package/src/checkpointer/checkpointSaverFactory.ts

@@ -0,0 +1,18 @@
+import { BaseCheckpointSaver, MemorySaver } from '@langchain/langgraph';
+import { MindedCheckpointSaver } from '../platform/mindedCheckpointSaver';
+import * as mindedConnection from '../platform/mindedConnection';
+import { logger } from '../utils/logger';
+
+/**
+ * Factory function to create the appropriate checkpoint saver based on environment variables.
+ * @returns BaseCheckpointSaver instance (either MemorySaver or MindedCheckpointSaver)
+ */
+export function createCheckpointSaver(): BaseCheckpointSaver {
+  if (!mindedConnection.isConnected()) {
+    logger.warn('mindedConnection not connected, falling back to in-memory checkpoint saver');
+    return new MemorySaver();
+  }
+
+  logger.debug('[Agent] Using remote checkpoint saver');
+  return new MindedCheckpointSaver();
+}

package/src/cli/index.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../utils/logger';
+import { execSync } from 'child_process';
+import { setupLocalOperator, isLocalOperatorSetup } from './localOperatorSetup';
+
+const ENV_FILE = '.env';
+
+function getEnvFilePath(): string {
+  return path.join(process.cwd(), ENV_FILE);
+}
+
+async function setToken(token: string): Promise<void> {
+  const envPath = getEnvFilePath();
+  const tokenLine = `MINDED_CONNECTION_TOKEN=${token}`;
+
+  // Check if .env file exists
+  if (!fs.existsSync(envPath)) {
+    // Create .env file with the token
+    fs.writeFileSync(envPath, tokenLine + '\n');
+    console.info(`Created ${envPath} and added token`);
+  } else {
+    // Read existing .env file
+    const envContent = fs.readFileSync(envPath, 'utf8');
+
+    // Check if MINDED_CONNECTION_TOKEN already exists
+    if (envContent.includes('MINDED_CONNECTION_TOKEN=')) {
+      // Replace existing token
+      const updatedContent = envContent.replace(/MINDED_CONNECTION_TOKEN=.*/, tokenLine);
+      fs.writeFileSync(envPath, updatedContent);
+      console.info(`Updated MINDED_CONNECTION_TOKEN in ${envPath}`);
+    } else {
+      // Append token to existing file
+      const newContent = envContent.endsWith('\n') ? envContent + tokenLine + '\n' : envContent + '\n' + tokenLine + '\n';
+      fs.writeFileSync(envPath, newContent);
+      logger.info({ msg: `Added MINDED_CONNECTION_TOKEN to ${envPath}` });
+    }
+  }
+}
+
+function generateLambdaHandler(): void {
+  const mindedConfigPath = path.join(process.cwd(), 'minded.json');
+
+  // Check if minded.json exists
+  if (!fs.existsSync(mindedConfigPath)) {
+    logger.error({ msg: 'minded.json not found in the current directory' });
+    process.exit(1);
+  }
+
+  // Read and parse minded.json
+  let mindedConfig;
+  try {
+    const configContent = fs.readFileSync(mindedConfigPath, 'utf8');
+    mindedConfig = JSON.parse(configContent);
+  } catch (err) {
+    logger.error({ message: 'Failed to read or parse minded.json:', err });
+    process.exit(1);
+  }
+
+  // Get the agent path
+  const agentPath = mindedConfig.agent;
+  if (!agentPath) {
+    logger.error({ msg: 'No agent path found in minded.json' });
+    process.exit(1);
+  }
+
+  // Remove .ts or .js extension if present and convert to relative path
+  const modulePath = agentPath.replace(/\.(ts|js)$/, '');
+
+  // Get the path to the template file
+  // Try multiple locations to support both development and npm package scenarios
+  const templatePaths = [
+    path.join(__dirname, 'lambdaHandlerTemplate.ts'), // For npm package
+    path.join(__dirname, '..', '..', 'src', 'cli', 'lambdaHandlerTemplate.ts'), // For development
+  ];
+
+  let templateContent: string | null = null;
+
+  // Try each path until we find the template
+  for (const templatePath of templatePaths) {
+    try {
+      if (fs.existsSync(templatePath)) {
+        templateContent = fs.readFileSync(templatePath, 'utf8');
+        logger.debug(`Found template at ${templatePath}`);
+        break;
+      }
+    } catch {
+      // Continue to next path
+    }
+  }
+
+  if (!templateContent) {
+    logger.error({ msg: 'Could not find Lambda handler template file' });
+    process.exit(1);
+  }
+
+  try {
+    // Replace the placeholder with the actual module path
+    templateContent = templateContent.replace(/{MODULE_PATH}/g, modulePath);
+
+    // Write the Lambda handler to index.ts at the root
+    const outputPath = path.join(process.cwd(), 'index.ts');
+    fs.writeFileSync(outputPath, templateContent);
+    logger.info({ msg: `Generated Lambda handler at ${outputPath}` });
+
+    // Compile the index.ts file using TypeScript
+    logger.info({ msg: 'Compiling the Lambda handler...' });
+
+    try {
+      // Read tsconfig.json to get the outDir
+      let outDir = 'dist'; // Default value
+      const tsconfigPath = path.join(process.cwd(), 'tsconfig.json');
+
+      if (fs.existsSync(tsconfigPath)) {
+        try {
+          const tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');
+          const tsconfig = JSON.parse(tsconfigContent);
+
+          if (tsconfig.compilerOptions && tsconfig.compilerOptions.outDir) {
+            outDir = tsconfig.compilerOptions.outDir;
+            logger.debug(`Using outDir from tsconfig.json: ${outDir}`);
+          }
+        } catch {
+          logger.warn('Failed to parse tsconfig.json, using default outDir: dist');
+        }
+      }
+
+      // Check if output directory exists, create if it doesn't
+      const distDir = path.join(process.cwd(), outDir);
+      if (!fs.existsSync(distDir)) {
+        fs.mkdirSync(distDir, { recursive: true });
+      }
+
+      // Compile index.ts to the configured output directory
+      execSync(`npx tsc --target ES2018 --module CommonJS --esModuleInterop ${outputPath} --outDir ${outDir}`, {
+        stdio: 'pipe',
+        cwd: process.cwd(),
+      });
+
+      logger.info({ msg: `Successfully compiled Lambda handler to ${outDir}/index.js` });
+    } catch (compileError) {
+      logger.error({ msg: 'Failed to compile Lambda handler', error: compileError });
+    }
+  } catch (err) {
+    logger.error({ message: 'Failed to generate Lambda handler', err });
+    process.exit(1);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command === 'token') {
+    const token = args[1];
+    if (!token) {
+      logger.error({ msg: 'Please provide a token' });
+      process.exit(1);
+    }
+    await setToken(token);
+  } else if (command === 'setup-local-operator') {
+    // Standalone command to setup local operator
+    const skipPrompt = args.includes('--yes') || args.includes('-y');
+    await setupLocalOperator(skipPrompt);
+  } else if (command === 'generate-lambda-ts-handler') {
+    generateLambdaHandler();
+  } else if (command === 'check-local-operator') {
+    // Command to check if local operator is set up
+    if (isLocalOperatorSetup()) {
+      console.info('✓ Local operator is set up and ready');
+    } else {
+      console.info('✗ Local operator is not set up. Run: npx minded setup-local-operator');
+      process.exit(1);
+    }
+  } else {
+    logger.error({
+      msg: 'Unknown command. Available commands: token, setup-local-operator, check-local-operator, generate-lambda-ts-handler',
+    });
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  logger.error({ message: 'Command failed', error });
+  process.exit(1);
+});

package/src/cli/lambdaHandlerTemplate.ts

@@ -0,0 +1,78 @@
+// @ts-expect-error - This import will be resolved at runtime in the generated Lambda handler
+import { logger } from '@minded-ai/mindedjs';
+
+// This is the template for the Lambda handler
+// The {MODULE_PATH} placeholder will be replaced with the actual path
+
+export const handler = async (event: any, context: any) => {
+  try {
+    const modulePath = '{MODULE_PATH}'; // Module path placeholder - DO NOT CHANGE THE {MODULE_PATH} TOKEN
+    const resolvedPath = require.resolve(modulePath);
+    delete require.cache[resolvedPath];
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const agent = require(modulePath).default;
+    const { agentFunctionName, agentFunctionBody } = event.body ? JSON.parse(event.body) : event;
+
+    if (!agent[agentFunctionName]) {
+      throw new Error('Unknown agentFunctionName: ' + agentFunctionName);
+    }
+
+    const response = await agent[agentFunctionName](agentFunctionBody);
+
+    // Safely stringify the response. If it fails (e.g., due to circular refs
+    // or non-serialisable class instances), fall back to null.
+    let responseBody = null;
+    try {
+      JSON.stringify(response);
+      responseBody = response;
+    } catch {
+      // ignored - responseBody stays null
+    }
+
+    if (agentFunctionName === 'startVoiceSession') {
+      while (context.getRemainingTimeInMillis() > 1000) {
+        logger.info({ msg: 'Lambda remaining time in seconds: ', remainingTime: context.getRemainingTimeInMillis() / 1000 });
+        await wait(1000); // sleep 1 s
+      }
+    }
+
+    // Close socket
+    await wait(500);
+    agent.onEnd?.();
+
+    return {
+      statusCode: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Credentials': true,
+      },
+      body: JSON.stringify(responseBody),
+    };
+  } catch (err: any) {
+    logger.error({
+      msg: 'Lambda runtime error',
+      err,
+      requestId: context.requestId,
+      functionName: context.functionName,
+    });
+
+    return {
+      statusCode: 500,
+      headers: {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Credentials': true,
+      },
+      body: JSON.stringify({
+        error: 'Lambda runtime error',
+        errorMessage: err.message,
+        errorStack: err.stack,
+        requestId: context.requestId,
+        functionName: context.functionName,
+      }),
+    };
+  }
+};
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));

package/src/cli/localOperatorSetup.ts

@@ -0,0 +1,308 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync, spawn } from 'child_process';
+import * as readline from 'readline';
+
+const VENV_DIR = '.venv';
+const SETUP_MARKER_FILE = '.minded-local-operator-setup';
+
+interface SetupPackage {
+  name: string;
+  description: string;
+  command: string;
+  checkCommand?: string;
+}
+
+const REQUIRED_PACKAGES: SetupPackage[] = [
+  {
+    name: 'uv',
+    description: 'Python package manager for fast dependency installation',
+    command: 'curl -LsSf https://astral.sh/uv/install.sh | sh',
+    checkCommand: 'uv --version',
+  },
+  {
+    name: 'Python 3.12',
+    description: 'Python runtime for browser automation',
+    command: 'python3.12 --version',
+    checkCommand: 'python3.12 --version',
+  },
+  {
+    name: 'browser-use',
+    description: 'Browser automation library',
+    command: 'uv pip install browser-use',
+  },
+  {
+    name: 'Playwright Chromium',
+    description: 'Chromium browser for automation',
+    command: 'uvx playwright install chromium --with-deps',
+  },
+];
+
+export function isLocalOperatorSetup(): boolean {
+  const setupMarkerPath = path.join(process.cwd(), SETUP_MARKER_FILE);
+  const venvPath = path.join(process.cwd(), VENV_DIR);
+
+  // Check if both the marker file and venv directory exist
+  return fs.existsSync(setupMarkerPath) && fs.existsSync(venvPath);
+}
+
+function checkCommand(command: string): boolean {
+  try {
+    execSync(command, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function promptUser(question: string): Promise<boolean> {
+  // Check if we're in an interactive terminal
+  if (!process.stdin.isTTY) {
+    console.warn('Non-interactive terminal detected, skipping prompt and cancelling installation');
+    return Promise.resolve(false);
+  }
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    // Set a timeout in case the prompt hangs
+    const timeout = setTimeout(() => {
+      console.warn('Prompt timeout (30s), cancelling installation');
+      rl.close();
+      resolve(false);
+    }, 30000); // 30 second timeout
+
+    console.log('Displaying prompt to user');
+
+    rl.question(question, (answer) => {
+      clearTimeout(timeout);
+      console.log(`User answered: "${answer}"`);
+
+      rl.close();
+
+      const confirmed = answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+      console.log(`Prompt result: ${confirmed}`);
+
+      resolve(confirmed);
+    });
+
+    // Handle potential readline errors
+    rl.on('error', (error) => {
+      console.error('Readline error, cancelling installation:', error.message);
+      clearTimeout(timeout);
+      rl.close();
+      resolve(false);
+    });
+  });
+}
+
+async function runCommand(command: string, description: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    console.log(`Installing ${description}...`);
+
+    const isComplexCommand = command.includes('|') || command.includes('&&');
+
+    if (isComplexCommand) {
+      // For complex commands with pipes or &&, use shell
+      const child = spawn('sh', ['-c', command], {
+        stdio: 'inherit',
+        shell: true,
+      });
+
+      child.on('error', (error) => {
+        console.error(`Failed to install ${description}:`, error.message);
+        reject(error);
+      });
+
+      child.on('close', (code) => {
+        if (code === 0) {
+          console.log(`✓ ${description} installed successfully`);
+          resolve();
+        } else {
+          reject(new Error(`Command exited with code ${code}`));
+        }
+      });
+    } else {
+      // For simple commands, use execSync
+      try {
+        execSync(command, { stdio: 'inherit' });
+        console.log(`✓ ${description} installed successfully`);
+        resolve();
+      } catch (error) {
+        console.error(`Failed to install ${description}:`, error);
+        reject(error);
+      }
+    }
+  });
+}
+
+export async function setupLocalOperator(skipPrompt: boolean = false): Promise<void> {
+  console.log('\n🤖 Minded Local Operator Setup\n');
+
+  // Check if already setup
+  if (isLocalOperatorSetup()) {
+    console.log('✓ Local operator is already set up');
+    return;
+  }
+
+  // Display what will be installed
+  console.log('The following packages will be installed for local browser automation:\n');
+  REQUIRED_PACKAGES.forEach((pkg, index) => {
+    console.log(`  ${index + 1}. ${pkg.name} - ${pkg.description}`);
+  });
+  console.log('');
+
+  // Ask for confirmation unless skipped
+  if (!skipPrompt) {
+    console.log('Waiting for user confirmation...');
+    const confirmed = await promptUser('Do you want to proceed with the installation? (y/n): ');
+    if (!confirmed) {
+      console.log('Installation cancelled by user');
+      process.exit(0);
+    }
+    console.log('User confirmed, proceeding with installation');
+  } else {
+    console.log('Skipping confirmation prompt, proceeding with installation...');
+  }
+
+  console.log('\n📦 Starting installation...\n');
+
+  try {
+    // Check and install uv if needed
+    if (!checkCommand('uv --version')) {
+      console.log('Installing uv package manager...');
+      await runCommand('curl -LsSf https://astral.sh/uv/install.sh | sh', 'uv');
+
+      // Add uv to PATH for current session
+      const uvPath = path.join(process.env.HOME || '', '.cargo', 'bin');
+      process.env.PATH = `${uvPath}:${process.env.PATH}`;
+    } else {
+      console.log('✓ uv is already installed');
+    }
+
+    // Check Python 3.12
+    if (!checkCommand('python3.12 --version')) {
+      console.error('Python 3.12 is required but not found');
+      console.log('Please install Python 3.12 manually:');
+      console.log('  macOS: brew install python@3.12');
+      console.log('  Ubuntu/Debian: sudo apt install python3.12');
+      console.log('  Or visit: https://www.python.org/downloads/');
+      process.exit(1);
+    } else {
+      console.log('✓ Python 3.12 is available');
+    }
+
+    // Create virtual environment
+    console.log('Creating Python virtual environment...');
+    execSync(`uv venv --python 3.12 ${VENV_DIR}`, { stdio: 'inherit' });
+    console.log('✓ Virtual environment created');
+
+    // Install browser-use in the venv
+    console.log('Installing browser-use package...');
+    execSync(`uv pip install --python ${path.join(process.cwd(), VENV_DIR, 'bin', 'python')} browser-use`, {
+      stdio: 'inherit',
+    });
+    console.log('✓ browser-use installed');
+
+    // Install Playwright Chromium
+    console.log('Installing Playwright Chromium browser...');
+    execSync(`uvx playwright install chromium --with-deps`, { stdio: 'inherit' });
+    console.log('✓ Playwright Chromium installed');
+
+    // Create setup marker file
+    const setupMarkerPath = path.join(process.cwd(), SETUP_MARKER_FILE);
+    const setupInfo = {
+      version: '1.0.0',
+      setupDate: new Date().toISOString(),
+      packages: REQUIRED_PACKAGES.map((p) => p.name),
+      venvPath: VENV_DIR,
+    };
+    fs.writeFileSync(setupMarkerPath, JSON.stringify(setupInfo, null, 2));
+
+    // Add to .gitignore if not already there
+    const gitignorePath = path.join(process.cwd(), '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+      const itemsToIgnore = [VENV_DIR, SETUP_MARKER_FILE, 'downloads/'];
+      const linesToAdd: string[] = [];
+
+      itemsToIgnore.forEach((item) => {
+        if (!gitignoreContent.includes(item)) {
+          linesToAdd.push(item);
+        }
+      });
+
+      if (linesToAdd.length > 0) {
+        const newContent = gitignoreContent.trimEnd() + '\n\n# Minded Local Operator\n' + linesToAdd.join('\n') + '\n';
+        fs.writeFileSync(gitignorePath, newContent);
+        console.log('✓ Updated .gitignore');
+      }
+    }
+
+    // Add BROWSER_TASK_MODE to .env file
+    const envPath = path.join(process.cwd(), '.env');
+    const browserTaskModeVar = 'BROWSER_TASK_MODE=localRun';
+
+    if (fs.existsSync(envPath)) {
+      const envContent = fs.readFileSync(envPath, 'utf8');
+
+      // Check if BROWSER_TASK_MODE is already set
+      if (!envContent.includes('BROWSER_TASK_MODE')) {
+        // Append to existing .env file
+        const newEnvContent = envContent.trimEnd() + '\n' + browserTaskModeVar + '\n';
+        fs.writeFileSync(envPath, newEnvContent);
+        console.log('✓ Added BROWSER_TASK_MODE=localRun to .env');
+      } else if (!envContent.includes('BROWSER_TASK_MODE=localRun')) {
+        // BROWSER_TASK_MODE exists but with different value, update it
+        const updatedEnvContent = envContent.replace(/BROWSER_TASK_MODE=.*$/m, browserTaskModeVar);
+        fs.writeFileSync(envPath, updatedEnvContent);
+        console.log('✓ Updated BROWSER_TASK_MODE to localRun in .env');
+      } else {
+        console.log('✓ BROWSER_TASK_MODE=localRun already configured in .env');
+      }
+    } else {
+      // Create new .env file
+      fs.writeFileSync(envPath, browserTaskModeVar + '\n');
+      console.log('✓ Created .env file with BROWSER_TASK_MODE=localRun');
+    }
+
+    console.log('\n' + '='.repeat(50));
+    console.log('✅ Local operator setup completed successfully!');
+    console.log('='.repeat(50) + '\n');
+
+    console.log('You can now use browser automation features locally.');
+    console.log('The virtual environment will be activated automatically when needed.');
+  } catch (error) {
+    console.error('Setup failed:', error);
+
+    // Clean up partial installation
+    try {
+      if (fs.existsSync(path.join(process.cwd(), VENV_DIR))) {
+        fs.rmSync(path.join(process.cwd(), VENV_DIR), { recursive: true });
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    process.exit(1);
+  }
+}
+
+export function validateLocalOperatorSetup(): void {
+  if (!isLocalOperatorSetup()) {
+    console.error('Local operator is not set up');
+    console.log('Please run: npx minded setup-local-operator');
+    throw new Error('Local operator not configured');
+  }
+}
+
+export function getVenvPath(): string {
+  return path.join(process.cwd(), VENV_DIR);
+}
+
+export function getVenvBinPath(): string {
+  return path.join(getVenvPath(), 'bin');
+}

package/src/debugging/index.ts

@@ -0,0 +1 @@
+export { LLMDebugCallbackHandler } from './llmCallbackHandler';