alumnium 0.22.0 → 0.23.0

package/README.md

@@ -15,7 +15,7 @@
     <a href="https://alumnium.ai/docs/">Documentation</a>
 </p>
 
-Alumnium is an AI-native library and MCP for end-to-end testing. It builds upon the existing test automation ecosystem and simplifies interactions with applications, providing more robust mechanisms for verifying assertions. It works with Appium, Playwright, or Selenium and gives you [state-of-the-art][7] capabilities.
+Alumnium is an AI-native library and MCP for end-to-end testing. It builds upon the existing test automation ecosystem and simplifies interactions with applications, providing more robust mechanisms for verifying assertions. It works with Appium, Maestro, Playwright, or Selenium and gives you [state-of-the-art][7] capabilities.
 
 https://github.com/user-attachments/assets/461050ba-f219-4ae2-bf5c-65faeb12b77e
 
@@ -69,12 +69,12 @@ import org.openqa.selenium.chrome.ChromeDriver;
 class AlumniumTest {
     public static void main(String...args) {
         ChromeDriver driver = new ChromeDriver();
-        Alumni alumni = new Alumni(driver);
+        Alumni al = new Alumni(driver);
         driver.get("https://search.brave.com");
-        alumni.act("type 'selenium' into the search field, then press 'Enter'");
-        alumni.check("page title contains selenium");
-        alumni.check("search results contain selenium.dev");
-        alumni.quit();
+        al.act("type 'selenium' into the search field, then press 'Enter'");
+        al.check("page title contains selenium");
+        al.check("search results contain selenium.dev");
+        al.quit();
     }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alumnium",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Pave the way towards AI-powered test automation",
   "keywords": [
     "ai",
@@ -62,26 +62,29 @@
     "optionalDependencies": {}
   },
   "dependencies": {
-    "@alumnium/langchain-codex": "^0.1.0",
+    "@ai-sdk/amazon-bedrock": "^5.0.61",
+    "@ai-sdk/anthropic": "^4.0.41",
+    "@ai-sdk/azure": "^4.0.48",
+    "@ai-sdk/deepseek": "^3.0.31",
+    "@ai-sdk/google": "^4.0.50",
+    "@ai-sdk/mistral": "^4.0.32",
+    "@ai-sdk/openai": "^4.0.46",
+    "@ai-sdk/provider": "^4.0.7",
+    "@ai-sdk/xai": "^4.0.43",
+    "@cursor/sdk": "1.0.30",
     "@js-fns/canon": "^0.2.0",
     "@js-fns/xxhash": "^0.1.0",
-    "@langchain/anthropic": "^1.3.20",
-    "@langchain/aws": "^1.2.5",
-    "@langchain/core": "^1.1.41",
-    "@langchain/deepseek": "^1.0.14",
-    "@langchain/google": "^0.1.10",
-    "@langchain/mistralai": "^1.0.5",
-    "@langchain/ollama": "^1.2.4",
-    "@langchain/openai": "^1.2.10",
-    "@langchain/xai": "^1.3.6",
     "@logtape/file": "^2.0.2",
     "@logtape/logtape": "^2.0.2",
     "@logtape/otel": "^2.0.5",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
     "@opentelemetry/resources": "^2.7.0",
     "@opentelemetry/sdk-trace-base": "^2.7.0",
     "@opentelemetry/sdk-trace-node": "^2.7.0",
+    "ai": "^7.0.78",
     "alwaysly": "^0.4.0",
     "cac": "^7.0.0",
     "case-anything": "^3.1.2",
@@ -92,8 +95,9 @@
     "entities": "^8.0.0",
     "filenamify": "^7.0.1",
     "htmlparser2": "^11.0.0",
-    "langchain-cursor": "^0.1.0",
     "nanoid": "^5.1.9",
+    "ollama-ai-provider-v2": "^4.0.1",
+    "openai-oauth": "1.0.2",
     "picocolors": "^1.1.1",
     "playwright-core": "^1.60.0",
     "selenium-webdriver": "^4.41.0",
@@ -104,7 +108,6 @@
   "devDependencies": {
     "@babel/plugin-proposal-decorators": "^7.29.0",
     "@elysiajs/cors": "^1.4.1",
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "@rolldown/plugin-babel": "^0.2.3",
     "@smithy/types": "^4.13.0",
     "@types/bun": "^1.3.14",
@@ -126,11 +129,11 @@
     "vitest": "^4.1.5"
   },
   "optionalDependencies": {
-    "@alumnium/cli-darwin-arm64": "0.22.0",
-    "@alumnium/cli-darwin-x64": "0.22.0",
-    "@alumnium/cli-linux-arm64": "0.22.0",
-    "@alumnium/cli-linux-x64": "0.22.0",
-    "@alumnium/cli-windows-arm64": "0.22.0",
-    "@alumnium/cli-windows-x64": "0.22.0"
+    "@alumnium/cli-darwin-arm64": "0.23.0",
+    "@alumnium/cli-darwin-x64": "0.23.0",
+    "@alumnium/cli-linux-arm64": "0.23.0",
+    "@alumnium/cli-linux-x64": "0.23.0",
+    "@alumnium/cli-windows-arm64": "0.23.0",
+    "@alumnium/cli-windows-x64": "0.23.0"
   }
 }

package/src/Env.d.ts

@@ -30,10 +30,10 @@ export declare const Env: {
   readonly ALUMNIUM_LOG_PATH: string | undefined;
   readonly ALUMNIUM_LOG_FILENAME: string | undefined;
   readonly ALUMNIUM_LOG_DEBUG_EXTRA: (
+    | "ai-sdk"
     | "all"
     | "env"
     | "http"
-    | "langchain"
     | "reasoning"
     | "scenarios"
     | "tree"
@@ -47,10 +47,16 @@ export declare const Env: {
   readonly ALUMNIUM_DRIVER:
     | "appium-android"
     | "appium-ios"
+    | "maestro"
     | "playwright"
     | "selenium";
   readonly ALUMNIUM_APPIUM_SERVER: string;
+  readonly ALUMNIUM_MAESTRO_PATH: string | undefined;
+  readonly ALUMNIUM_MAESTRO_OS: "android" | "ios";
+  readonly ANDROID_HOME: string | undefined;
+  readonly ANDROID_SDK_ROOT: string | undefined;
   readonly ALUMNIUM_MODEL: Model;
+  readonly ALUMNIUM_MCP_MODE: "agentic" | "direct";
   readonly ALUMNIUM_MCP_RECORD_VIDEOS: boolean;
   readonly ALUMNIUM_MCP_ARTIFACTS_DIR: string | undefined;
   readonly ALUMNIUM_MCP_PROFILES_DIR: string | undefined;
@@ -60,6 +66,7 @@ export declare const Env: {
   readonly ALUMNIUM_MODEL_RETRIES: number;
   readonly ALUMNIUM_MODEL_TIMEOUT: number;
   readonly ALUMNIUM_OLLAMA_URL: string | undefined;
+  readonly LANGCHAIN_CODEX_LITTERBOX_UPLOAD: boolean;
   readonly ALUMNIUM_PLANNER: boolean;
   readonly ALUMNIUM_RETRIES: number;
   readonly ALUMNIUM_NO_RETRY: boolean;
@@ -85,10 +92,8 @@ export declare const Env: {
   readonly AWS_REGION_NAME: string;
   readonly AWS_SECRET_KEY: string | undefined;
   readonly AZURE_FOUNDRY_API_KEY: string | undefined;
-  readonly AZURE_FOUNDRY_API_VERSION: string | undefined;
   readonly AZURE_FOUNDRY_TARGET_URI: string | undefined;
   readonly AZURE_OPENAI_API_KEY: string | undefined;
-  readonly AZURE_OPENAI_API_VERSION: string | undefined;
   readonly AZURE_OPENAI_DEFAULT_HEADERS: Record<string, string> | undefined;
   readonly AZURE_OPENAI_ENDPOINT: string | undefined;
   readonly CURSOR_API_KEY: string | undefined;
@@ -99,6 +104,7 @@ export declare const Env: {
   readonly OPENAI_API_KEY: string | undefined;
   readonly OPENAI_CUSTOM_URL: string | undefined;
   readonly OPENAI_DEFAULT_HEADERS: Record<string, string> | undefined;
+  readonly OPENROUTER_API_KEY: string | undefined;
   readonly XAI_API_KEY: string | undefined;
   readonly LT_USERNAME: string | undefined;
   readonly LT_ACCESS_KEY: string | undefined;
@@ -107,4 +113,5 @@ export declare const Env: {
   readonly VITEST_WORKER_ID: number | undefined;
   reset(): void;
   init(logger: LoggerSchema.Like): Env.InspectResult;
+  log: boolean;
 };

package/src/Model.d.ts

@@ -20,6 +20,7 @@ declare const ModelProvider: z.ZodEnum<{
   mistralai: "mistralai";
   ollama: "ollama";
   openai: "openai";
+  openrouter: "openrouter";
   xai: "xai";
 }>;
 declare const ModelDev: z.ZodEnum<{
@@ -32,6 +33,7 @@ declare const ModelDev: z.ZodEnum<{
   openai: "openai";
   xai: "xai";
 }>;
+export declare const defaultModelProvider: Model.Provider;
 export declare const Model: {
   Provider: z.ZodEnum<{
     anthropic: "anthropic";
@@ -46,6 +48,7 @@ export declare const Model: {
     mistralai: "mistralai";
     ollama: "ollama";
     openai: "openai";
+    openrouter: "openrouter";
     xai: "xai";
   }>;
   Dev: z.ZodEnum<{

package/src/accessibility/AccessibilityElement.d.ts

@@ -10,6 +10,7 @@ export interface AccessibilityElement {
   androidText?: string | undefined;
   androidContentDesc?: string | undefined;
   androidBounds?: string | undefined;
+  maestroBounds?: string | undefined;
   frame?: object | undefined;
   frameChain?: number[] | undefined;
 }

package/src/accessibility/MaestroAccessibilityTree.d.ts

@@ -0,0 +1,32 @@
+import type { MaestroSession } from "../drivers/MaestroSession.ts";
+import type { AccessibilityElement } from "./AccessibilityElement.ts";
+import { BaseAccessibilityTree } from "./BaseAccessibilityTree.ts";
+export declare namespace MaestroAccessibilityTree {
+  /** Role names inferred from the attributes Maestro provides. */
+  type Role = "TextField" | "CheckBox" | "Button" | "Text" | "View";
+}
+/**
+ * Maestro's view hierarchy, rendered as XML with `raw_id` markers.
+ *
+ * Maestro normalizes iOS and Android into one flat shape of `{attributes, children}`, which means
+ * it drops the platform element type — there is no `XCUIElementTypeButton` or
+ * `android.widget.TextView` to key off. Roles are therefore inferred from the attributes that do
+ * survive, and most nodes end up as the generic `View` that the server tree collapses away.
+ */
+export declare class MaestroAccessibilityTree extends BaseAccessibilityTree<MaestroSession.Hierarchy> {
+  #private;
+  protected get kind(): string;
+  constructor(hierarchy: MaestroSession.Hierarchy);
+  /** Renders the hierarchy as XML, stamping `raw_id` on every node. */
+  toStr(): string;
+  /** True when any node in the hierarchy carries the given `resource-id`. */
+  hasResourceId(resourceId: string): boolean;
+  elementById(rawId: number): AccessibilityElement;
+  /** Scopes the tree to the subtree rooted at `rawId`. */
+  scopeToArea(rawId: number): MaestroAccessibilityTree;
+  /** Parses the centre point of a Maestro `[x1,y1][x2,y2]` bounds string. */
+  static centreOf(bounds: string): {
+    x: number;
+    y: number;
+  };
+}

package/src/accessibility/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./AccessibilityElement.ts";
 export * from "./BaseAccessibilityTree.ts";
 export * from "./ChromiumAccessibilityTree.ts";
+export * from "./MaestroAccessibilityTree.ts";
 export * from "./UIAutomator2AccessibilityTree.ts";
 export * from "./XCUITestAccessibilityTree.ts";

package/src/client/Alumni.d.ts

@@ -1,11 +1,11 @@
-import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import type { Page } from "playwright-core";
 import { WebDriver } from "selenium-webdriver";
 import type { Browser } from "webdriverio";
 import { Client } from "../clients/Client.ts";
 import type { Data } from "../clients/typecasting.ts";
-import { BaseDriver, type Element } from "../drivers/index.ts";
+import { BaseDriver, type Element, MaestroSession } from "../drivers/index.ts";
 import { LlmUsageStats } from "../llm/llmSchema.ts";
+import type { LanguageModel } from "../llm/LanguageModel.ts";
 import { Model } from "../Model.ts";
 import { NavigationPolicy } from "../NavigationPolicy.ts";
 import { type ToolClass } from "../tools/BaseTool.ts";
@@ -21,11 +21,11 @@ export type AlumniOptions = Alumni.Options;
  */
 export type VisionOptions = Alumni.VisionOptions;
 export declare namespace Alumni {
-  type Driver = WebDriver | Page | Browser;
+  type Driver = WebDriver | Page | Browser | MaestroSession;
   interface Options {
     url?: string | undefined;
     model?: Model | undefined;
-    llm?: BaseChatModel | undefined;
+    llm?: LanguageModel | undefined;
     extraTools?: ToolClass[];
     planner?: boolean | undefined;
     changeAnalysis?: boolean | undefined;