opensteer 0.6.0 → 0.6.2

package/dist/index.js

@@ -1,8 +1,10 @@
+import {
+  BrowserProfileClient
+} from "./chunk-WJI7TGBQ.js";
 import {
   ActionWsClient,
-  CloudCdpClient,
-  CloudSessionClient,
   CounterResolutionError,
+  CursorController,
   ElementPathError,
   LocalSelectorStorage,
   OPENSTEER_HIDDEN_ATTR,
@@ -22,8 +24,8 @@ import {
   OpensteerAgentError,
   OpensteerAgentExecutionError,
   OpensteerAgentProviderError,
-  OpensteerCloudError,
   OpensteerCuaAgentHandler,
+  SvgCursorRenderer,
   buildArrayFieldPathCandidates,
   buildElementPathFromHandle,
   buildElementPathFromSelector,
@@ -36,9 +38,7 @@ import {
   clearCookies,
   cloneElementPath,
   closeTab,
-  cloudNotLaunchedError,
   cloudSessionContractVersion,
-  cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries,
   countArrayItemsWithPath,
   createCuaClient,
@@ -58,13 +58,13 @@ import {
   importCookies,
   listTabs,
   markInteractiveElements,
-  normalizeNamespace,
   performClick,
   performFileUpload,
   performHover,
   performInput,
   performScroll,
   performSelect,
+  planSnappyCursorMotion,
   prepareSnapshot,
   pressKey,
   queryAllByElementPath,
@@ -72,14 +72,22 @@ import {
   resolveCounterElement,
   resolveCountersBatch,
   resolveElementPath,
-  resolveNamespaceDir,
   sanitizeElementPath,
   serializePageHTML,
   setCookie,
   switchTab,
   typeText,
   waitForVisualStability
-} from "./chunk-SGZYTGY3.js";
+} from "./chunk-F2VDVOJO.js";
+import {
+  CloudCdpClient,
+  CloudSessionClient,
+  OpensteerCloudError,
+  cloudNotLaunchedError,
+  cloudUnsupportedMethodError,
+  normalizeNamespace,
+  resolveNamespaceDir
+} from "./chunk-WDRMHPWL.js";
 import {
   createResolveCallback
 } from "./chunk-DN3GI5CH.js";
@@ -90,11 +98,196 @@ import "./chunk-3H5RRIMZ.js";
 import {
   getModelProvider
 } from "./chunk-FAHE5DB2.js";
+
+// src/cursor/renderers/cdp-overlay.ts
+var PULSE_DELAY_MS = 30;
+var CdpOverlayCursorRenderer = class {
+  page = null;
+  session = null;
+  active = false;
+  reason = "disabled";
+  lastMessage;
+  lastPoint = null;
+  async initialize(page) {
+    this.page = page;
+    if (page.isClosed()) {
+      this.markInactive("page_closed");
+      return;
+    }
+    await this.createSession();
+  }
+  isActive() {
+    return this.active;
+  }
+  status() {
+    return {
+      enabled: true,
+      active: this.active,
+      reason: this.reason ? this.lastMessage ? `${this.reason}: ${this.lastMessage}` : this.reason : void 0
+    };
+  }
+  async move(point, style) {
+    await this.sendWithRecovery(async (session) => {
+      await session.send("Overlay.highlightQuad", {
+        quad: buildCursorQuad(point, style.size),
+        color: toProtocolRgba(style.fillColor),
+        outlineColor: toProtocolRgba(style.outlineColor)
+      });
+    });
+    this.lastPoint = point;
+  }
+  async pulse(point, style) {
+    const pulseSize = style.size * style.pulseScale;
+    const pulseFill = {
+      ...style.fillColor,
+      a: Math.min(1, style.fillColor.a * 0.14)
+    };
+    const pulseOutline = {
+      ...style.haloColor,
+      a: Math.min(1, style.haloColor.a * 0.9)
+    };
+    await this.sendWithRecovery(async (session) => {
+      await session.send("Overlay.highlightQuad", {
+        quad: buildCursorQuad(point, pulseSize),
+        color: toProtocolRgba(pulseFill),
+        outlineColor: toProtocolRgba(pulseOutline)
+      });
+    });
+    await sleep(PULSE_DELAY_MS);
+    await this.move(point, style);
+  }
+  async clear() {
+    if (!this.session) return;
+    try {
+      await this.session.send("Overlay.hideHighlight");
+    } catch {
+      this.markInactive("cdp_detached");
+    }
+  }
+  async dispose() {
+    await this.cleanupSession();
+    this.active = false;
+    this.reason = "disabled";
+    this.lastMessage = void 0;
+    this.lastPoint = null;
+    this.page = null;
+  }
+  async sendWithRecovery(operation) {
+    if (!this.active || !this.session) return;
+    try {
+      await operation(this.session);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.lastMessage = message;
+      if (!isRecoverableProtocolError(message) || !this.page) {
+        this.markInactive("renderer_error", message);
+        return;
+      }
+      await this.createSession();
+      if (!this.active || !this.session) {
+        return;
+      }
+      try {
+        await operation(this.session);
+      } catch (retryError) {
+        const retryMessage = retryError instanceof Error ? retryError.message : String(retryError);
+        this.markInactive("renderer_error", retryMessage);
+      }
+    }
+  }
+  async createSession() {
+    if (!this.page || this.page.isClosed()) {
+      this.markInactive("page_closed");
+      return;
+    }
+    await this.cleanupSession();
+    try {
+      const session = await this.page.context().newCDPSession(this.page);
+      await session.send("DOM.enable");
+      await session.send("Overlay.enable");
+      this.session = session;
+      this.active = true;
+      this.reason = void 0;
+      this.lastMessage = void 0;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.markInactive(inferSetupReason(message), message);
+      await this.cleanupSession();
+    }
+  }
+  async cleanupSession() {
+    const session = this.session;
+    this.session = null;
+    if (!session) return;
+    try {
+      await session.detach();
+    } catch {
+    }
+  }
+  markInactive(reason, message) {
+    this.active = false;
+    this.reason = reason;
+    this.lastMessage = message;
+  }
+};
+function buildCursorQuad(point, size) {
+  const x = point.x;
+  const y = point.y;
+  return [
+    // Point 0: Tip (the hotspot)
+    roundPointValue(x),
+    roundPointValue(y),
+    // Point 1: Right shoulder — extends right and down
+    roundPointValue(x + size * 0.45),
+    roundPointValue(y + size * 0.78),
+    // Point 2: Tail — bottom of the cursor shaft
+    roundPointValue(x + size * 0.12),
+    roundPointValue(y + size * 1.3),
+    // Point 3: Left edge — stays close to the shaft
+    roundPointValue(x - size * 0.04),
+    roundPointValue(y + size * 0.62)
+  ];
+}
+function inferSetupReason(message) {
+  const lowered = message.toLowerCase();
+  if (lowered.includes("not supported") || lowered.includes("only supported") || lowered.includes("unknown command")) {
+    return "unsupported";
+  }
+  return "cdp_unavailable";
+}
+function isRecoverableProtocolError(message) {
+  const lowered = message.toLowerCase();
+  return lowered.includes("session closed") || lowered.includes("target closed") || lowered.includes("has been closed") || lowered.includes("detached");
+}
+function toProtocolRgba(color) {
+  return {
+    r: clampColor(color.r),
+    g: clampColor(color.g),
+    b: clampColor(color.b),
+    a: clampAlpha(color.a)
+  };
+}
+function clampColor(value) {
+  return Math.min(255, Math.max(0, Math.round(value)));
+}
+function clampAlpha(value) {
+  const normalized = Number.isFinite(value) ? value : 1;
+  return Math.min(1, Math.max(0, normalized));
+}
+function roundPointValue(value) {
+  return Math.round(value * 100) / 100;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export {
   ActionWsClient,
+  BrowserProfileClient,
+  CdpOverlayCursorRenderer,
   CloudCdpClient,
   CloudSessionClient,
   CounterResolutionError,
+  CursorController,
   ElementPathError,
   LocalSelectorStorage,
   OPENSTEER_HIDDEN_ATTR,
@@ -116,6 +309,7 @@ export {
   OpensteerAgentProviderError,
   OpensteerCloudError,
   OpensteerCuaAgentHandler,
+  SvgCursorRenderer,
   buildArrayFieldPathCandidates,
   buildElementPathFromHandle,
   buildElementPathFromSelector,
@@ -160,6 +354,7 @@ export {
   performInput,
   performScroll,
   performSelect,
+  planSnappyCursorMotion,
   prepareSnapshot,
   pressKey,
   queryAllByElementPath,

package/dist/types-BxiRblC7.d.cts

@@ -0,0 +1,327 @@
+import { BrowserContextOptions } from 'playwright';
+
+type MatchOperator = 'exact' | 'startsWith' | 'contains';
+interface AttributeMatchClause {
+    kind: 'attr';
+    key: string;
+    op?: MatchOperator;
+    value?: string;
+}
+interface PositionMatchClause {
+    kind: 'position';
+    axis: 'nthOfType' | 'nthChild';
+}
+type MatchClause = AttributeMatchClause | PositionMatchClause;
+interface PathNodePosition {
+    nthChild: number;
+    nthOfType: number;
+}
+interface PathNode {
+    tag: string;
+    attrs: Record<string, string>;
+    position: PathNodePosition;
+    match: MatchClause[];
+}
+type DomPath = PathNode[];
+interface ContextHop {
+    kind: 'iframe' | 'shadow';
+    host: DomPath;
+}
+interface ElementPath {
+    context: ContextHop[];
+    nodes: DomPath;
+}
+
+type SnapshotMode = 'action' | 'extraction' | 'clickable' | 'scrollable' | 'full';
+interface SnapshotOptions {
+    mode?: SnapshotMode;
+    withCounters?: boolean;
+    markInteractive?: boolean;
+}
+interface ScreenshotOptions {
+    fullPage?: boolean;
+    type?: 'png' | 'jpeg';
+    /** Ignored for PNG. */
+    quality?: number;
+    omitBackground?: boolean;
+}
+interface AiResolveArgs {
+    html: string;
+    action: string;
+    description: string;
+    url: string | null;
+}
+interface AiResolveResult {
+    element?: number;
+    selector?: string;
+    path?: ElementPath;
+}
+type AiResolveCallbackResult = AiResolveResult | number | string | null | undefined;
+type AiResolveCallback = (args: AiResolveArgs) => Promise<AiResolveCallbackResult>;
+interface AiExtractArgs<TSchema = ExtractSchema> {
+    html: string;
+    schema: TSchema;
+    description?: string;
+    prompt?: string;
+    url: string | null;
+}
+type AiExtractResult<TData = unknown> = TData | ExtractionPlan | string;
+type AiExtractCallback = <TSchema = ExtractSchema, TData = unknown>(args: AiExtractArgs<TSchema>) => Promise<AiExtractResult<TData>>;
+interface GotoOptions {
+    timeout?: number;
+    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
+    settleMs?: number;
+}
+interface LaunchOptions {
+    headless?: boolean;
+    executablePath?: string;
+    slowMo?: number;
+    context?: BrowserContextOptions;
+    /** Connect to a running browser. Example: "http://localhost:9222" */
+    connectUrl?: string;
+    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
+    channel?: string;
+    /** Browser profile directory or Chromium user-data dir. Preserves cookies, extensions, and sessions. */
+    profileDir?: string;
+    /** Cloud browser profile preference. Applies only when cloud mode is enabled. */
+    cloudBrowserProfile?: OpensteerCloudBrowserProfileOptions;
+    /** Connection timeout in milliseconds. */
+    timeout?: number;
+}
+interface OpensteerBrowserConfig {
+    headless?: boolean;
+    executablePath?: string;
+    slowMo?: number;
+    /** Connect to a running browser. Example: "http://localhost:9222" */
+    connectUrl?: string;
+    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
+    channel?: string;
+    /** Browser profile directory or Chromium user-data dir. Preserves cookies, extensions, and sessions. */
+    profileDir?: string;
+}
+interface OpensteerStorageConfig {
+    rootDir?: string;
+}
+interface OpensteerCursorColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+interface OpensteerCursorStyle {
+    size?: number;
+    fillColor?: OpensteerCursorColor;
+    outlineColor?: OpensteerCursorColor;
+    haloColor?: OpensteerCursorColor;
+    pulseScale?: number;
+}
+type OpensteerCursorProfile = 'snappy';
+interface OpensteerCursorConfig {
+    enabled?: boolean;
+    profile?: OpensteerCursorProfile;
+    style?: OpensteerCursorStyle;
+}
+type OpensteerAuthScheme = 'api-key' | 'bearer';
+type OpensteerCloudAnnouncePolicy = 'always' | 'off' | 'tty';
+interface OpensteerCloudBrowserProfileOptions {
+    profileId: string;
+    reuseIfActive?: boolean;
+}
+interface OpensteerCloudOptions {
+    apiKey?: string;
+    accessToken?: string;
+    baseUrl?: string;
+    authScheme?: OpensteerAuthScheme;
+    announce?: OpensteerCloudAnnouncePolicy;
+    browserProfile?: OpensteerCloudBrowserProfileOptions;
+}
+type OpensteerCloudConfig = boolean | OpensteerCloudOptions;
+interface OpensteerConfig {
+    name?: string;
+    browser?: OpensteerBrowserConfig;
+    storage?: OpensteerStorageConfig;
+    cursor?: OpensteerCursorConfig;
+    cloud?: OpensteerCloudConfig;
+    model?: string;
+    debug?: boolean;
+}
+interface ActionWaitOptions {
+    enabled?: boolean;
+    timeout?: number;
+    settleMs?: number;
+    networkQuietMs?: number;
+    includeNetwork?: boolean;
+}
+interface BaseActionOptions {
+    description?: string;
+    element?: number;
+    selector?: string;
+    wait?: false | ActionWaitOptions;
+}
+interface ClickOptions extends BaseActionOptions {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
+}
+interface HoverOptions extends BaseActionOptions {
+    force?: boolean;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+interface InputOptions extends BaseActionOptions {
+    text: string;
+    clear?: boolean;
+    pressEnter?: boolean;
+}
+interface SelectOptions extends BaseActionOptions {
+    value?: string;
+    label?: string;
+    index?: number;
+}
+interface ScrollOptions extends BaseActionOptions {
+    direction?: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+}
+interface ExtractSchemaField {
+    element?: number;
+    selector?: string;
+    attribute?: string;
+    source?: 'current_url';
+}
+type ExtractSchemaValue = ExtractSchemaField | string | number | boolean | null | ExtractSchema | ExtractSchema[];
+interface ExtractSchema {
+    [key: string]: ExtractSchemaValue;
+}
+interface ExtractOptions<TSchema = ExtractSchema> extends BaseActionOptions {
+    schema?: TSchema;
+    prompt?: string;
+    snapshot?: SnapshotOptions;
+}
+interface ExtractionFieldPlan {
+    element?: number;
+    selector?: string;
+    attribute?: string;
+    source?: 'current_url';
+}
+interface ExtractionPlan {
+    fields?: Record<string, ExtractionFieldPlan>;
+    paths?: Record<string, ElementPath>;
+    data?: unknown;
+}
+interface ExtractFromPlanOptions<TSchema = ExtractSchema> {
+    description?: string;
+    schema: TSchema;
+    plan: ExtractionPlan;
+}
+interface ActionResult {
+    method: string;
+    namespace: string;
+    persisted: boolean;
+    pathFile: string | null;
+    selectorUsed?: string | null;
+}
+interface OpensteerCursorState {
+    enabled: boolean;
+    active: boolean;
+    reason?: string;
+}
+interface ExtractionRunResult<T = unknown> {
+    namespace: string;
+    persisted: boolean;
+    pathFile: string | null;
+    data: T;
+    paths: Record<string, ElementPath>;
+}
+interface StateResult {
+    url: string;
+    title: string;
+    html: string;
+}
+interface TabInfo {
+    index: number;
+    url: string;
+    title: string;
+    active: boolean;
+}
+interface CookieParam {
+    name: string;
+    value: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+interface FileUploadOptions extends BaseActionOptions {
+    paths: string[];
+}
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type OpensteerAgentMode = 'cua';
+type OpensteerAgentProvider = 'openai' | 'anthropic' | 'google';
+interface OpensteerAgentModelConfig {
+    modelName: string;
+    apiKey?: string;
+    baseUrl?: string;
+    organization?: string;
+    thinkingBudget?: number;
+    environment?: string;
+}
+interface OpensteerAgentConfig {
+    mode: OpensteerAgentMode;
+    model?: string | OpensteerAgentModelConfig;
+    systemPrompt?: string;
+    waitBetweenActionsMs?: number;
+}
+interface OpensteerAgentExecuteOptions {
+    instruction: string;
+    maxSteps?: number;
+    highlightCursor?: boolean;
+}
+interface OpensteerAgentUsage {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    inferenceTimeMs: number;
+}
+interface OpensteerAgentAction {
+    type: string;
+    reasoning?: string;
+    button?: string;
+    clickCount?: number;
+    x?: number;
+    y?: number;
+    text?: string;
+    keys?: string[];
+    scrollX?: number;
+    scrollY?: number;
+    timeMs?: number;
+    url?: string;
+    path?: Array<{
+        x: number;
+        y: number;
+    }>;
+    [key: string]: unknown;
+}
+interface OpensteerAgentResult {
+    success: boolean;
+    completed: boolean;
+    message: string;
+    actions: OpensteerAgentAction[];
+    usage?: OpensteerAgentUsage;
+    provider: OpensteerAgentProvider;
+    model: string;
+}
+interface OpensteerAgentInstance {
+    execute(instructionOrOptions: string | OpensteerAgentExecuteOptions): Promise<OpensteerAgentResult>;
+}
+
+export type { OpensteerBrowserConfig as $, ActionResult as A, BaseActionOptions as B, CookieParam as C, AiResolveArgs as D, ExtractOptions as E, FileUploadOptions as F, GotoOptions as G, HoverOptions as H, InputOptions as I, AiResolveCallbackResult as J, AiResolveResult as K, LaunchOptions as L, AttributeMatchClause as M, ContextHop as N, OpensteerAuthScheme as O, DomPath as P, ExtractSchema as Q, ExtractSchemaField as R, SnapshotOptions as S, TabInfo as T, ExtractSchemaValue as U, ExtractionFieldPlan as V, ExtractionPlan as W, MatchClause as X, MatchOperator as Y, OpensteerAgentMode as Z, OpensteerAgentModelConfig as _, OpensteerConfig as a, OpensteerCloudAnnouncePolicy as a0, OpensteerCloudBrowserProfileOptions as a1, OpensteerCloudConfig as a2, OpensteerCloudOptions as a3, OpensteerCursorColor as a4, OpensteerCursorProfile as a5, OpensteerStorageConfig as a6, PathNode as a7, PathNodePosition as a8, PositionMatchClause as a9, StateResult as b, ScreenshotOptions as c, ClickOptions as d, SelectOptions as e, ScrollOptions as f, BoundingBox as g, ExtractFromPlanOptions as h, ExtractionRunResult as i, OpensteerCursorState as j, OpensteerAgentConfig as k, OpensteerAgentInstance as l, ElementPath as m, SnapshotMode as n, AiResolveCallback as o, AiExtractCallback as p, OpensteerAgentProvider as q, OpensteerAgentAction as r, OpensteerAgentResult as s, OpensteerAgentUsage as t, OpensteerCursorStyle as u, OpensteerCursorConfig as v, OpensteerAgentExecuteOptions as w, ActionWaitOptions as x, AiExtractArgs as y, AiExtractResult as z };