@minded-ai/mindedjs 3.1.46 → 3.1.49

package/src/platform/config.ts

@@ -3,6 +3,7 @@ import { config } from 'dotenv';
 import { Environment } from '../types/Platform.types';
 import { BrowserTaskMode } from '../browserTask/types';
 import { logger } from '../utils/logger';
+import { MindedProxyMode, ProxyConfig, ProxyProvider } from '../types/Tools.types';
 const path = resolve(__dirname, '../../.env');
 config({ path });
 
@@ -18,6 +19,7 @@ type MindedConfig = {
   elevenLabsKey: string | null;
   elevenLabsAgentId: string | null;
   browserTaskMode: BrowserTaskMode;
+  proxyConfig: ProxyConfig | null;
   isDeprioritizedSocket: boolean;
 };
 
@@ -37,8 +39,73 @@ const parseBrowserTaskMode = (value: string | undefined): BrowserTaskMode => {
   return BrowserTaskMode.CLOUD;
 };
 
+const parseProxyConfig = (): ProxyConfig | null => {
+  const provider = process.env.BROWSER_PROXY_PROVIDER?.trim();
+  if (!provider) {
+    return null;
+  }
+
+  if (provider === ProxyProvider.MINDED) {
+    const mode = process.env.BROWSER_PROXY_MODE?.trim();
+    if (mode === MindedProxyMode.TRUSTED_IP) {
+      return {
+        provider: ProxyProvider.MINDED,
+        mode: MindedProxyMode.TRUSTED_IP,
+      };
+    }
+    if (mode === MindedProxyMode.REGION) {
+      const countryCode = process.env.BROWSER_PROXY_COUNTRY_CODE?.trim();
+      if (!countryCode) {
+        logger.warn({
+          message: 'BROWSER_PROXY_COUNTRY_CODE is required when BROWSER_PROXY_MODE is region; ignoring proxy config',
+        });
+        return null;
+      }
+      return {
+        provider: ProxyProvider.MINDED,
+        mode: MindedProxyMode.REGION,
+        countryCode,
+      };
+    }
+    logger.warn({
+      message: 'Invalid BROWSER_PROXY_MODE provided; ignoring proxy config',
+      provided: mode,
+      allowed: [MindedProxyMode.TRUSTED_IP, MindedProxyMode.REGION],
+    });
+    return null;
+  }
+
+  if (provider === ProxyProvider.CUSTOM) {
+    const server = process.env.BROWSER_PROXY_SERVER?.trim();
+    if (!server) {
+      logger.warn({
+        message: 'BROWSER_PROXY_SERVER is required when BROWSER_PROXY_PROVIDER is custom; ignoring proxy config',
+      });
+      return null;
+    }
+    const username = process.env.BROWSER_PROXY_USERNAME?.trim();
+    const password = process.env.BROWSER_PROXY_PASSWORD?.trim();
+    return {
+      provider: ProxyProvider.CUSTOM,
+      server,
+      ...(username ? { username } : {}),
+      ...(password ? { password } : {}),
+    };
+  }
+
+  logger.warn({
+    message: 'Invalid BROWSER_PROXY_PROVIDER provided; ignoring proxy config',
+    provided: provider,
+    allowed: [ProxyProvider.MINDED, ProxyProvider.CUSTOM],
+  });
+  return null;
+};
+
 export const getConfig = (): MindedConfig => {
   const environment = (process.env.NODE_ENV as Environment) || Environment.DEVELOPMENT;
+  const browserTaskMode = parseBrowserTaskMode(process.env.BROWSER_TASK_MODE);
+  const proxyConfig = parseProxyConfig();
+
   switch (environment) {
     case Environment.TEST:
       return {
@@ -52,7 +119,8 @@ export const getConfig = (): MindedConfig => {
         dashboardConnected: false,
         elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
         elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || null,
-        browserTaskMode: parseBrowserTaskMode(process.env.BROWSER_TASK_MODE),
+        browserTaskMode,
+        proxyConfig,
         isDeprioritizedSocket: process.env.IS_DEPRIORITIZED_SOCKET === 'true',
       };
     case Environment.DEVELOPMENT:
@@ -67,7 +135,8 @@ export const getConfig = (): MindedConfig => {
         elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
         dashboardConnected: true,
         elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'agent_01jye194psezr909nwec27m2t9',
-        browserTaskMode: parseBrowserTaskMode(process.env.BROWSER_TASK_MODE),
+        browserTaskMode,
+        proxyConfig,
         isDeprioritizedSocket: process.env.IS_DEPRIORITIZED_SOCKET === 'true',
       };
     case Environment.STAGING:
@@ -82,7 +151,8 @@ export const getConfig = (): MindedConfig => {
         elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
         dashboardConnected: false,
         elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'agent_01jye1ajkaf17axpcxg220qwcm',
-        browserTaskMode: parseBrowserTaskMode(process.env.BROWSER_TASK_MODE),
+        browserTaskMode,
+        proxyConfig,
         isDeprioritizedSocket: process.env.IS_DEPRIORITIZED_SOCKET === 'true',
       };
     case Environment.PRODUCTION:
@@ -97,7 +167,8 @@ export const getConfig = (): MindedConfig => {
         elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
         dashboardConnected: false,
         elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'agent_01jye1ajkaf17axpcxg220qwcm',
-        browserTaskMode: parseBrowserTaskMode(process.env.BROWSER_TASK_MODE),
+        browserTaskMode,
+        proxyConfig,
         isDeprioritizedSocket: process.env.IS_DEPRIORITIZED_SOCKET === 'true',
       };
   }

package/src/platform/mindedConnectionTypes.ts

@@ -18,6 +18,8 @@ export enum mindedConnectionSocketMessageType {
   SAVE_STORAGE_RECORD = 'save-storage-record',
   GET_STORAGE_RECORDS = 'get-storage-records',
   DELETE_STORAGE_RECORD = 'delete-storage-record',
+  ACQUIRE_DISTRIBUTED_LOCK = 'acquire-distributed-lock',
+  RELEASE_DISTRIBUTED_LOCK = 'release-distributed-lock',
   GET_AGENT_CONFIGURATION = 'get-agent-configuration',
   GET_FLOWS = 'get-flows',
   GET_PLAYBOOKS = 'get-playbooks',
@@ -99,6 +101,8 @@ export type mindedConnectionSocketMessageTypeMap = {
   [mindedConnectionSocketMessageType.SAVE_STORAGE_RECORD]: SaveStorageRecordRequest;
   [mindedConnectionSocketMessageType.GET_STORAGE_RECORDS]: GetStorageRecordsRequest;
   [mindedConnectionSocketMessageType.DELETE_STORAGE_RECORD]: DeleteStorageRecordRequest;
+  [mindedConnectionSocketMessageType.ACQUIRE_DISTRIBUTED_LOCK]: AcquireDistributedLockRequest;
+  [mindedConnectionSocketMessageType.RELEASE_DISTRIBUTED_LOCK]: ReleaseDistributedLockRequest;
   [mindedConnectionSocketMessageType.GET_FLOWS]: BasemindedConnectionSocketMessage;
   [mindedConnectionSocketMessageType.GET_PLAYBOOKS]: BasemindedConnectionSocketMessage;
   [mindedConnectionSocketMessageType.INVOKE]: InvokeMessage;
@@ -813,6 +817,27 @@ export interface DeleteStorageRecordResponse extends BaseSdkConnectionSocketMess
   success?: boolean;
 }
 
+export interface AcquireDistributedLockRequest extends BasemindedConnectionSocketMessage {
+  type: mindedConnectionSocketMessageType.ACQUIRE_DISTRIBUTED_LOCK;
+  key: string;
+  ttlSeconds?: number;
+}
+
+export interface AcquireDistributedLockResponse extends BaseSdkConnectionSocketMessageResponseCallbackAck {
+  acquired?: boolean;
+  lockId?: string;
+}
+
+export interface ReleaseDistributedLockRequest extends BasemindedConnectionSocketMessage {
+  type: mindedConnectionSocketMessageType.RELEASE_DISTRIBUTED_LOCK;
+  key: string;
+  lockId: string;
+}
+
+export interface ReleaseDistributedLockResponse extends BaseSdkConnectionSocketMessageResponseCallbackAck {
+  released?: boolean;
+}
+
 export interface RPAErrorUploadRequest extends BasemindedConnectionSocketMessage {
   type: mindedConnectionSocketMessageType.RPA_ERROR_UPLOAD;
   sessionId: string;

package/src/platform/toolExecutor.ts

@@ -2,7 +2,7 @@ import { Tool } from '../types/Tools.types';
 import { Agent } from '../agent';
 import { logger } from '../utils/logger';
 import { withBrowserSession } from '../toolsLibrary/withBrowserSession';
-import { getConfig } from './config';
+import { resolveRpaBrowserSessionOptions } from '../browserTask/resolveRpaBrowserSessionOptions';
 
 export interface ToolExecutionRequest {
   toolName: string;
@@ -86,9 +86,10 @@ export class ToolExecutor {
 
       // Check if this is an RPA tool
       if (tool.type === 'rpa') {
-        const configBrowserTaskMode = getConfig().browserTaskMode;
-        // Use tool's browserTaskMode if provided, otherwise fall back to config
-        const browserTaskMode = tool.browserTaskMode ?? configBrowserTaskMode;
+        const { browserTaskMode, proxyConfig } = resolveRpaBrowserSessionOptions({
+          toolBrowserTaskMode: tool.browserTaskMode,
+          toolProxyConfig: tool.proxyConfig,
+        });
 
         // Wrap with browser session and screenshot capture
         const { result, breakpointHit, breakpointInfo } = await withBrowserSession(
@@ -96,7 +97,7 @@ export class ToolExecutor {
             sessionId,
             browserTaskMode,
             toolCallId: requestId, // Use requestId as toolCallId for tracking
-            proxyConfig: tool.proxyConfig,
+            proxyConfig,
             toolName,
             persistSession: tool.persistSession,
           },

package/src/toolsLibrary/distributedLock.ts

@@ -0,0 +1,160 @@
+import { awaitEmit } from '../platform/mindedConnection';
+import {
+  mindedConnectionSocketMessageType,
+  AcquireDistributedLockRequest,
+  AcquireDistributedLockResponse,
+  ReleaseDistributedLockRequest,
+  ReleaseDistributedLockResponse,
+} from '../platform/mindedConnectionTypes';
+import { logger } from '../utils/logger';
+import { wait } from '../utils/wait';
+
+const LOCK_KEY_PATTERN = /^[a-zA-Z0-9:_-]{1,128}$/;
+const DEFAULT_TTL_SECONDS = 90;
+const DEFAULT_WAIT_MS = 60_000;
+const DEFAULT_RETRY_INTERVAL_MS = 500;
+const SOCKET_TIMEOUT_MS = 10_000;
+
+interface AcquireLockParams {
+  key: string;
+  ttlSeconds?: number;
+  waitMs?: number;
+  retryIntervalMs?: number;
+  sessionId?: string;
+}
+
+interface ReleaseLockParams {
+  key: string;
+  lockId: string;
+  sessionId?: string;
+}
+
+interface WithLockParams {
+  key: string;
+  ttlSeconds?: number;
+  waitMs?: number;
+  retryIntervalMs?: number;
+  sessionId?: string;
+}
+
+export class DistributedLockTimeoutError extends Error {
+  constructor(key: string, waitMs: number) {
+    super(`Timed out waiting ${waitMs}ms to acquire distributed lock "${key}"`);
+    this.name = 'DistributedLockTimeoutError';
+  }
+}
+
+const assertValidLockKey = (key: string) => {
+  if (!LOCK_KEY_PATTERN.test(key)) {
+    throw new Error('Lock key must be 1-128 characters of letters, numbers, colon, underscore, or hyphen');
+  }
+};
+
+const tryAcquireOnce = async ({ key, ttlSeconds }: { key: string; ttlSeconds: number }): Promise<string | null> => {
+  const request: AcquireDistributedLockRequest = {
+    type: mindedConnectionSocketMessageType.ACQUIRE_DISTRIBUTED_LOCK,
+    key,
+    ttlSeconds,
+  };
+
+  const response = await awaitEmit<AcquireDistributedLockRequest, AcquireDistributedLockResponse>(
+    mindedConnectionSocketMessageType.ACQUIRE_DISTRIBUTED_LOCK,
+    request,
+    SOCKET_TIMEOUT_MS,
+  );
+
+  if (response.error) {
+    throw new Error(response.error);
+  }
+
+  if (response.acquired === true && response.lockId) {
+    return response.lockId;
+  }
+
+  return null;
+};
+
+export const acquireLock = async ({
+  key,
+  ttlSeconds = DEFAULT_TTL_SECONDS,
+  waitMs = DEFAULT_WAIT_MS,
+  retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS,
+  sessionId,
+}: AcquireLockParams): Promise<string> => {
+  assertValidLockKey(key);
+  const deadline = Date.now() + waitMs;
+
+  const initialLockId = await tryAcquireOnce({ key, ttlSeconds });
+  if (initialLockId !== null) {
+    logger.info({
+      message: 'Acquired distributed lock',
+      key,
+      sessionId,
+    });
+    return initialLockId;
+  }
+
+  while (Date.now() < deadline) {
+    await wait(retryIntervalMs);
+    const lockId = await tryAcquireOnce({ key, ttlSeconds });
+    if (lockId !== null) {
+      logger.info({
+        message: 'Acquired distributed lock',
+        key,
+        sessionId,
+      });
+      return lockId;
+    }
+  }
+
+  throw new DistributedLockTimeoutError(key, waitMs);
+};
+
+export const releaseLock = async ({ key, lockId, sessionId }: ReleaseLockParams): Promise<void> => {
+  assertValidLockKey(key);
+  if (!lockId) {
+    throw new Error('lockId is required in releaseLock params');
+  }
+
+  const request: ReleaseDistributedLockRequest = {
+    type: mindedConnectionSocketMessageType.RELEASE_DISTRIBUTED_LOCK,
+    key,
+    lockId,
+  };
+
+  const response = await awaitEmit<ReleaseDistributedLockRequest, ReleaseDistributedLockResponse>(
+    mindedConnectionSocketMessageType.RELEASE_DISTRIBUTED_LOCK,
+    request,
+    SOCKET_TIMEOUT_MS,
+  );
+
+  if (response.error) {
+    throw new Error(response.error);
+  }
+
+  if (response.released === false) {
+    logger.warn({
+      message: 'Distributed lock was not released; it may have expired',
+      key,
+      sessionId,
+    });
+  }
+};
+
+export const withLock = async <T>(params: WithLockParams, callback: () => Promise<T>): Promise<T> => {
+  const lockId = await acquireLock(params);
+  try {
+    return await callback();
+  } finally {
+    try {
+      await releaseLock({ key: params.key, lockId, sessionId: params.sessionId });
+    } catch (error) {
+      logger.warn({
+        message: 'Failed to release distributed lock',
+        key: params.key,
+        sessionId: params.sessionId,
+        error,
+      });
+    }
+  }
+};

package/src/toolsLibrary/index.ts

@@ -4,6 +4,8 @@ import * as extraction from './extraction';
 import * as resolveCaptcha from './resolveCaptcha';
 import * as storage from './storage';
 
+export * as lock from './distributedLock';
+
 // Export all tools as a collection for easy discovery
 export const tools = {
   'minded-parse-documents': parseDocument,