@alumnium/core 0.0.0-stage → 0.24.0-alpha.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Alexey Rodionov, Tatiana Shepeleva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @alumnium/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Alumnium core: Alumni, agents, environment, telemetry, storage, accessibility trees, tools and driver contracts. See [the main `alumnium` package page](https://www.npmjs.com/package/alumnium) for more details.

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@alumnium/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.24.0-alpha.2",
+  "description": "Alumnium core: Alumni, agents, environment, telemetry, storage, accessibility trees, tools and driver contracts",
+  "license": "MIT",
+  "author": "Alex Rodionov <p0deje@gmail.com>",
+  "contributors": [
+    "Alex Rodionov <p0deje@gmail.com>",
+    "Sasha Koss <koss@nocorp.me>",
+    "Tatiana Shepeleva <tati.shep@gmail.com>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alumnium-hq/alumnium.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.cjs"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./src/internal.d.ts",
+        "default": "./src/internal.js"
+      },
+      "require": {
+        "types": "./src/internal.d.ts",
+        "default": "./src/internal.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "^4.0.7",
+    "@js-fns/canon": "^0.2.0",
+    "@js-fns/xxhash": "^0.1.0",
+    "@logtape/file": "^2.0.2",
+    "@logtape/logtape": "^2.0.2",
+    "@opentelemetry/api": "^1.9.1",
+    "alwaysly": "^0.4.0",
+    "cac": "^7.0.0",
+    "case-anything": "^3.1.2",
+    "diff": "^8.0.3",
+    "domelementtype": "^3.0.0",
+    "domhandler": "^6.0.0",
+    "domutils": "^3.2.2",
+    "filenamify": "^7.0.1",
+    "htmlparser2": "^11.0.0",
+    "nanoid": "^5.1.9",
+    "picocolors": "^1.1.1",
+    "smollit": "^0.2.0",
+    "zod": "^4.4.1"
+  },
+  "peerDependencies": {
+    "@alumnium/telemetry": "0.24.0-alpha.2",
+    "ai": "^7.0.78"
+  },
+  "peerDependenciesMeta": {
+    "@alumnium/telemetry": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    }
+  }
+}

package/src/AgentKind.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Kinds of Alumnium agents. Kept free of agent implementations so lightweight
+ * modules (e.g. telemetry) can reference them without pulling in the agents.
+ */
+export type AgentKind =
+  | "actor"
+  | "area"
+  | "changes-analyzer"
+  | "locator"
+  | "planner"
+  | "retriever";

package/src/AppId.d.ts

@@ -0,0 +1,8 @@
+import z from "zod";
+export declare const AppId: z.core.$ZodBranded<
+  z.ZodPipe<z.ZodCatch<z.ZodString>, z.ZodTransform<string, string>>,
+  "AppId",
+  "out"
+>;
+export type AppId = z.infer<typeof AppId>;
+export declare const UNKNOWN_APP_ID: AppId;

package/src/Env.d.ts

@@ -0,0 +1,122 @@
+import { Model } from "./Model.ts";
+import { LoggerSchema } from "./telemetry/LoggerSchema.ts";
+export declare namespace Env {
+  type VarsRecord = Record<string, unknown>;
+  interface InspectResult {
+    vars: VarsRecord;
+    valid: boolean;
+  }
+  type Var = keyof typeof Env;
+}
+export declare const Env: {
+  readonly ALUMNIUM_CACHE: "filesystem" | "sqlite" | boolean;
+  readonly ALUMNIUM_CACHE_PATH: string | undefined;
+  readonly ALUMNIUM_CHANGE_ANALYSIS: boolean;
+  /**
+   * Pre-installed Cursor SDK node_modules tree for compiled binaries in
+   * air-gapped environments; skips the download-on-first-use install.
+   */
+  readonly ALUMNIUM_CURSOR_SDK_DIR: string | undefined;
+  readonly ALUMNIUM_DELAY: number;
+  readonly ALUMNIUM_EXCLUDE_ATTRIBUTES: any[];
+  readonly ALUMNIUM_FULL_PAGE_SCREENSHOT: boolean;
+  readonly ALUMNIUM_LOG_LEVEL:
+    | "debug"
+    | "error"
+    | "fatal"
+    | "info"
+    | "trace"
+    | "warning";
+  readonly ALUMNIUM_LOG_PATH: string | undefined;
+  readonly ALUMNIUM_LOG_FILENAME: string | undefined;
+  readonly ALUMNIUM_LOG_DEBUG_EXTRA: (
+    | "ai-sdk"
+    | "all"
+    | "env"
+    | "http"
+    | "reasoning"
+    | "scenarios"
+    | "tree"
+  )[];
+  readonly ALUMNIUM_LOG_OBJECTS_DEPTH: number;
+  readonly ALUMNIUM_LOG_MAX_STR_LENGTH: number;
+  readonly ALUMNIUM_PRUNE_LOGS: boolean;
+  readonly ALUMNIUM_LOG_BUFFER_SIZE: number;
+  readonly ALUMNIUM_LOG_FLUSH_INTERVAL: number;
+  readonly ALUMNIUM_TRACE: boolean;
+  readonly ALUMNIUM_DRIVER:
+    | "appium-android"
+    | "appium-ios"
+    | "cloakbrowser"
+    | "maestro"
+    | "playwright"
+    | "selenium"
+    | "xcode";
+  readonly ALUMNIUM_APPIUM_SERVER: string;
+  readonly ALUMNIUM_MAESTRO_PATH: string | undefined;
+  readonly ALUMNIUM_MAESTRO_OS: "android" | "ios";
+  readonly ALUMNIUM_XCODE_AUTO_APPROVE: boolean;
+  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_TRACE_SCREENSHOTS: boolean;
+  readonly ALUMNIUM_MCP_TRACE_SNAPSHOTS: boolean;
+  readonly ALUMNIUM_MCP_ARTIFACTS_DIR: string | undefined;
+  readonly ALUMNIUM_MCP_PROFILES_DIR: string | undefined;
+  readonly ALUMNIUM_SERVER_URL: string | undefined;
+  readonly ALUMNIUM_SERVER_DAEMONIZE: boolean;
+  readonly ALUMNIUM_SERVER_PID_PATH: string | undefined;
+  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;
+  readonly ALUMNIUM_STORE_DIR: string;
+  readonly ALUMNIUM_PLAYWRIGHT_HEADLESS: boolean;
+  readonly ALUMNIUM_SELENIUM_BROWSER_VERSION: string | undefined;
+  readonly ALUMNIUM_TEST_MAX_CONCURRENCY: number;
+  readonly ALUMNIUM_TEST_RETRY_COUNT: number;
+  readonly ALUMNIUM_TEST_RETRY_DELAY: number;
+  readonly ALUMNIUM_DEV_DATA_TYPES_SCAN: boolean;
+  readonly ALUMNIUM_DEV_CAPTURE_TREES: boolean;
+  readonly ALUMNIUM_DEV_DRILL_TEST_TREES: boolean;
+  readonly ALUMNIUM_TEST_PASS_THRESHOLD_PCT: number;
+  readonly ALUMNIUM_EVAL_TRIAL_COUNT: number;
+  readonly ALUMNIUM_EVAL_RUN_TIMEOUT_MIN: number;
+  readonly ALUMNIUM_EVAL_MAX_CONCURRENCY: number;
+  readonly ALUMNIUM_EVAL_SESSION_NAME: string | undefined;
+  readonly ALUMNIUM_EVAL_SESSION_PATH: string | undefined;
+  readonly ALUMNIUM_EVAL_SESSION_TRIM_INPUT: number | false;
+  readonly ALUMNIUM_EVAL_THRESHOLD_PCT: number;
+  readonly ANTHROPIC_API_KEY: string | undefined;
+  readonly AWS_ACCESS_KEY: string | undefined;
+  readonly AWS_REGION_NAME: string;
+  readonly AWS_SECRET_KEY: string | undefined;
+  readonly AZURE_FOUNDRY_API_KEY: string | undefined;
+  readonly AZURE_FOUNDRY_TARGET_URI: string | undefined;
+  readonly AZURE_OPENAI_API_KEY: string | undefined;
+  readonly AZURE_OPENAI_DEFAULT_HEADERS: Record<string, string> | undefined;
+  readonly AZURE_OPENAI_ENDPOINT: string | undefined;
+  readonly CURSOR_API_KEY: string | undefined;
+  readonly DEEPSEEK_API_KEY: string | undefined;
+  readonly GOOGLE_API_KEY: string | undefined;
+  readonly MISTRAL_API_KEY: string | undefined;
+  readonly OLLAMA_HOST: string | undefined;
+  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;
+  readonly CI: boolean;
+  readonly GITHUB_ACTIONS: boolean;
+  readonly VITEST_WORKER_ID: number | undefined;
+  reset(): void;
+  init(logger: LoggerSchema.Like): Env.InspectResult;
+  log: boolean;
+};

package/src/FileStore/FileStore.d.ts

@@ -0,0 +1,148 @@
+import type z from "zod";
+export declare namespace FileStore {
+  type DirGetter = () => string;
+}
+/**
+ * File system-based store for state persistence, caching, artifacts, etc.
+ */
+export declare class FileStore {
+  protected static DYNAMIC_DIR_SYMBOL: symbol;
+  /**
+   * Creates a new FileStore instance for the specified directory. When the
+   * `dir` parameter is `FileStore.DYNAMIC_DIR_SYMBOL`, the store is expected to
+   * implement dynamic directory resolution by overriding the `dir` getter.
+   *
+   * @param dir Directory path for the store or `FileStore.DYNAMIC_DIR_SYMBOL` for dynamic resolution.
+   */
+  constructor(dir: string | typeof FileStore.DYNAMIC_DIR_SYMBOL);
+  protected defineDir(get: FileStore.DirGetter): void;
+  /**
+   * Store directory path.
+   */
+  get dir(): string;
+  /**
+   * Resolves a relative path against the store's directory. It doesn't create
+   * the directory structure or check for file existence.
+   *
+   * @param relPath Store-relative path
+   * @returns Resolved absolute path.
+   */
+  resolve(relPath: string): string;
+  /**
+   * Ensures that a file exists at the specified relative path, creating any
+   * necessary directories. Returns the resolved file path.
+   *
+   * @param relPath Store-relative file path
+   * @returns The resolved file path.
+   */
+  ensureFilePath(relPath: string): Promise<string>;
+  /**
+   * Ensures that a directory exists at the specified relative path, creating it
+   * if necessary. Returns the resolved directory path.
+   *
+   * @param relPath Store-relative directory path
+   * @returns The resolved directory path.
+   */
+  ensureDir(relPath: string): Promise<string>;
+  /**
+   * Writes JSON-serializable data to a file at the specified relative path,
+   * ensuring that the directory structure exists. Returns the resolved file path
+   * after writing.
+   *
+   * @param relPath Store-relative file path
+   * @param data JSON-serializable data to write to the file.
+   * @returns The resolved file path.
+   */
+  writeJson(relPath: string, data: unknown): Promise<string>;
+  /**
+   * Writes data to a file at the specified relative path, ensuring that the
+   * directory structure exists. Returns the resolved file path after writing.
+   *
+   * @param relPath Store-relative file path
+   * @param data Data to write to the file.
+   * @returns The resolved file path.
+   */
+  writeFile(relPath: string, data: Buffer | string): Promise<string>;
+  /**
+   * Reads file content as a string from the specified relative path. If
+   * the file doesn't exist, it returns null.
+   */
+  readText(relPath: string): Promise<string | null>;
+  /**
+   * Reads file content as JSON from the specified relative path. If
+   * the file doesn't exist, it returns null.
+   */
+  readJson<Type>(
+    relPath: string,
+    Schema?: z.Schema<Type>,
+  ): Promise<Type | null>;
+  /**
+   * Removes the store directory.
+   */
+  clear(): Promise<void>;
+  /**
+   * Removes a single file at the specified relative path. Doesn't throw if
+   * the file doesn't exist.
+   *
+   * @param relPath Store-relative file path
+   */
+  remove(relPath: string): Promise<void>;
+  /**
+   * Renames (moves) a file from one store-relative path to another.
+   *
+   * @param fromRelPath Store-relative source file path
+   * @param toRelPath Store-relative destination file path
+   */
+  rename(fromRelPath: string, toRelPath: string): Promise<void>;
+  /**
+   * Returns the last-modified time (in milliseconds since epoch) of the file
+   * at the specified relative path, or `null` if it doesn't exist.
+   *
+   * @param relPath Store-relative file path
+   */
+  mtime(relPath: string): Promise<number | null>;
+  /**
+   * Creates a sub-store under the current store directory. The subdirectory is
+   * resolved from the specified relative (to the current store directory) path.
+   *
+   * @param subDir Relative subdirectory path.
+   * @returns FileStore instance for the resolved subdirectory.
+   */
+  subStore(subDir: string): FileStore;
+  /**
+   * Creates a sub-store under the global store directory. The subdirectory can
+   * be configured via environment variable or resolved from the specified
+   * relative (to the global store directory `.alumnium`) path.
+   *
+   * @param envDir Environment variable value, e.g. `Env.ALUMNIUM_MCP_ARTIFACTS_DIR`.
+   * @param defaultDir Default subdirectory under global store, e.g. `artifacts`.
+   * @param nestedDir Optional nested directory under the resolved subdirectory, e.g. driver ID.
+   * @returns FileStore instance for the resolved directory.
+   */
+  static subStore(
+    envDir: string | undefined,
+    defaultDir: string,
+    nestedDir?: string,
+  ): FileStore;
+  /**
+   * Creates a store at a path relative to the current working directory.
+   *
+   * @param nestedDir Optional directory under the current working directory.
+   * @returns FileStore instance for the resolved directory.
+   */
+  static cwdRelStore(nestedDir?: string): FileStore;
+  /**
+   * Resolves a subdirectory path under the global store directory, allowing
+   * override via environment variable.
+   *
+   * @param envDir Environment variable value, e.g. `Env.ALUMNIUM_MCP_ARTIFACTS_DIR`.
+   * @param defaultDir Default subdirectory under global store, e.g. `artifacts`.
+   * @param nestedDir Optional nested directory under the resolved subdirectory, e.g. driver ID.
+   * @returns Resolved path.
+   */
+  static subResolve(
+    envDir: string | undefined,
+    defaultDir: string,
+    nestedDir?: string,
+  ): string;
+}

package/src/FileStore/GlobalFileStorePaths.d.ts

@@ -0,0 +1,15 @@
+export declare abstract class GlobalFileStorePaths {
+  /**
+   * Returns the global store directory path, which can be overridden via
+   * the `ALUMNIUM_STORE_DIR` environment variable. It defaults to `.alumnium`.
+   * @returns The global store directory path.
+   */
+  static get globalDir(): string;
+  /**
+   * Resolves a subdirectory path under the global store directory.
+   *
+   * @param dir Relative subdirectory path.
+   * @returns The resolved path.
+   */
+  static globalSubDir(dir: string): string;
+}

package/src/Http.d.ts

@@ -0,0 +1,3 @@
+export declare namespace Http {
+  type Method = "GET" | "POST" | "PUT" | "DELETE";
+}

package/src/Model.d.ts

@@ -0,0 +1,72 @@
+import z from "zod";
+export declare namespace Model {
+  type Provider = z.infer<typeof ModelProvider>;
+  type Dev = z.infer<typeof ModelDev>;
+}
+export interface Model {
+  provider: Model.Provider;
+  name: string;
+}
+declare const ModelProvider: z.ZodEnum<{
+  anthropic: "anthropic";
+  aws_anthropic: "aws_anthropic";
+  aws_meta: "aws_meta";
+  azure_foundry: "azure_foundry";
+  azure_openai: "azure_openai";
+  codex: "codex";
+  cursor: "cursor";
+  deepseek: "deepseek";
+  google: "google";
+  mistralai: "mistralai";
+  ollama: "ollama";
+  openai: "openai";
+  openrouter: "openrouter";
+  xai: "xai";
+}>;
+declare const ModelDev: z.ZodEnum<{
+  anthropic: "anthropic";
+  deepseek: "deepseek";
+  google: "google";
+  meta: "meta";
+  mistralai: "mistralai";
+  ollama: "ollama";
+  openai: "openai";
+  xai: "xai";
+}>;
+export declare const defaultModelProvider: Model.Provider;
+export declare const Model: {
+  Provider: z.ZodEnum<{
+    anthropic: "anthropic";
+    aws_anthropic: "aws_anthropic";
+    aws_meta: "aws_meta";
+    azure_foundry: "azure_foundry";
+    azure_openai: "azure_openai";
+    codex: "codex";
+    cursor: "cursor";
+    deepseek: "deepseek";
+    google: "google";
+    mistralai: "mistralai";
+    ollama: "ollama";
+    openai: "openai";
+    openrouter: "openrouter";
+    xai: "xai";
+  }>;
+  Dev: z.ZodEnum<{
+    anthropic: "anthropic";
+    deepseek: "deepseek";
+    google: "google";
+    meta: "meta";
+    mistralai: "mistralai";
+    ollama: "ollama";
+    openai: "openai";
+    xai: "xai";
+  }>;
+  "new"(
+    providerStr: string | Model.Provider,
+    nameStr: string | undefined,
+  ): Model;
+  parse(modelStr: string): Model;
+  toString(modelId: Model): string;
+  defaultProviderModel(provider: Model.Provider): string;
+};
+export {};

package/src/NavigationPolicy.d.ts

@@ -0,0 +1,39 @@
+export declare class NavigationPolicyConfigError extends Error {
+  constructor(
+    field: keyof NavigationPolicy.Options,
+    value: string,
+    cause: unknown,
+  );
+}
+/** Thrown by {@link NavigationPolicy.check} when a URL is blocked. */
+export declare class NavigationBlockedError extends Error {
+  constructor(url: string, reason: string);
+}
+export declare namespace NavigationPolicy {
+  interface Options {
+    allowedDomains?: string[] | undefined;
+    deniedDomains?: string[] | undefined;
+    allowedFilePaths?: string[] | undefined;
+  }
+  interface Evaluation {
+    allowed: boolean;
+    reason?: string;
+  }
+}
+/**
+ * Per-session allowlist/denylist for navigation targets. Patterns are case-insensitive regexes
+ * matched against the hostname and the full URL.
+ *
+ * - Without `allowedDomains`: everything is allowed except denylist matches.
+ * - With `allowedDomains`: only allowlist matches are allowed (an allowlist match beats a
+ *   denylist match).
+ *
+ * `allowedFilePaths` overrides both for matching `file://` URLs.
+ */
+export declare class NavigationPolicy {
+  #private;
+  private constructor();
+  static create(options: NavigationPolicy.Options): NavigationPolicy;
+  evaluate(url: string): NavigationPolicy.Evaluation;
+  check(url: string): void;
+}

package/src/accessibility/AccessibilityElement.d.ts

@@ -0,0 +1,17 @@
+export interface AccessibilityElement {
+  id?: number | undefined;
+  backendNodeId?: number | undefined;
+  name?: string | undefined;
+  label?: string | undefined;
+  type?: string | undefined;
+  value?: string | undefined;
+  index?: number | undefined;
+  androidResourceId?: string | undefined;
+  androidClass?: string | undefined;
+  androidText?: string | undefined;
+  androidContentDesc?: string | undefined;
+  androidBounds?: string | undefined;
+  maestroBounds?: string | undefined;
+  frame?: object | undefined;
+  frameChain?: number[] | undefined;
+}

package/src/accessibility/BaseAccessibilityTree.d.ts

@@ -0,0 +1,28 @@
+import { FileStore } from "../FileStore/FileStore.ts";
+import type { AccessibilityElement } from "./AccessibilityElement.ts";
+export declare abstract class BaseAccessibilityTree<Source = unknown> {
+  #private;
+  static sourceIdFor(
+    this: void,
+    kind: string,
+    source: unknown,
+  ): BaseAccessibilityTree.SourceId;
+  protected get kind(): string;
+  constructor(source: Source);
+  abstract toStr(): string;
+  abstract elementById(id: number): AccessibilityElement;
+  abstract scopeToArea(rawId: number): BaseAccessibilityTree<Source>;
+  protected set xml(xml: string);
+  protected get xml(): string | null;
+  static devTreesStore: FileStore;
+  static devSourceIdForXml(
+    xml: string,
+  ): BaseAccessibilityTree.SourceId | undefined;
+}
+export declare namespace BaseAccessibilityTree {
+  type SourceId = string & {
+    [sourceIdBrand]: never;
+  };
+}
+declare const sourceIdBrand: unique symbol;
+export {};

package/src/accessibility/ChromiumAccessibilityTree.d.ts

@@ -0,0 +1,24 @@
+import type { AccessibilityElement } from "./AccessibilityElement.ts";
+import { BaseAccessibilityTree } from "./BaseAccessibilityTree.ts";
+export declare class ChromiumAccessibilityTree extends BaseAccessibilityTree<
+  Record<string, unknown> | string
+> {
+  #private;
+  private nextRawId;
+  protected get kind(): string;
+  constructor(
+    cdpResponseOrXml: Record<string, unknown> | string,
+    frameMap?: Record<number, object>,
+  );
+  /** Convert CDP response to raw XML format preserving all data. */
+  toStr(): string;
+  /**
+   * Find element by raw_id and return its properties for element finding.
+   *
+   * @param rawId The raw_id to search for
+   * @returns AccessibilityElement with backend_node_id set
+   */
+  elementById(rawId: number): AccessibilityElement;
+  /** Scope the tree to a smaller subtree identified by raw_id. */
+  scopeToArea(rawId: number): ChromiumAccessibilityTree;
+}

package/src/agents.d.ts

@@ -0,0 +1,10 @@
+export * from "./clients/NativeClient.ts";
+export * from "./server/agents/ActorAgent.ts";
+export * from "./server/agents/AreaAgent.ts";
+export * from "./server/agents/ChangesAnalyzerAgent.ts";
+export * from "./server/agents/LocatorAgent.ts";
+export * from "./server/agents/PlannerAgent.ts";
+export * from "./server/agents/RetrieverAgent.ts";
+export * from "./server/cache/ElementsCache/ElementsCacheTree.ts";
+export * from "./server/session/Session.ts";
+export * from "./server/session/SessionManager.ts";

package/src/bundle.d.ts

@@ -0,0 +1 @@
+export declare function isSingleFileExecutable(): boolean;

package/src/cli/CliCommand.d.ts

@@ -0,0 +1,39 @@
+import type { CAC } from "cac";
+import { z } from "zod";
+export declare namespace CliCommand {
+  interface DefineProps<ArgsSchema extends z.ZodObject> {
+    name: string;
+    description: string;
+    Args: ArgsSchema;
+    action: NoInfer<ActionFn<z.infer<ArgsSchema>>>;
+  }
+  interface Definition<Args> {
+    name: string;
+    description: string;
+    action: ActionFn<Args>;
+    register: (cli: CAC) => void;
+    cli?: CAC | undefined;
+  }
+  type ActionFn<Args> = (props: ActionProps<Args>) => Promise<void>;
+  interface ActionProps<Args> {
+    args: Args;
+    logFilenameHint: string;
+  }
+}
+export declare abstract class CliCommand {
+  static define<ArgsSchema extends z.ZodObject>(
+    props: CliCommand.DefineProps<ArgsSchema>,
+  ): CliCommand.Definition<z.infer<ArgsSchema>>;
+  static option: z.core.$ZodRegistry<
+    {
+      name: string;
+      syntax: string;
+      description: string;
+    },
+    z.core.$ZodType<
+      unknown,
+      unknown,
+      z.core.$ZodTypeInternals<unknown, unknown>
+    >
+  >;
+}