Changelog

OpenTelemetry traces and metrics — every LLM call, act(), extract(), and agent step is instrumented.

• addedOpenTelemetry support — 6 span types (sentinel.agent → sentinel.agent.step → sentinel.act → sentinel.llm, plus sentinel.extract, sentinel.observe) and 6 metrics (act.requests, act.duration_ms, llm.requests, llm.tokens, llm.duration_ms, agent.steps). Zero overhead when no OTel SDK is configured.
• fixedActionResult.selector was discarded by the outer Sentinel.act() wrapper — now correctly forwarded from ActionEngine.

Stable CSS selector export after every run() — paste directly into Playwright tests.

• addedAgentResult.selectors — camelCase slug of each instruction maps to the most stable CSS selector found. Priority: data-testid → #id → [name] → [placeholder] → [aria-label] → role:has-text.
• addedActionResult.selector — single act() calls now also expose the selector for the acted-on element.
• addedslugifyInstruction() exported from @isoldex/sentinel — converts a natural-language instruction to a camelCase key.

Prompt caching — identical (prompt, schema) pairs return instantly at zero token cost.

• addedpromptCache option (false | true | string) — in-memory LRU (200 entries) or file-persisted cache keyed by djb2 hash of prompt + schema. Covers act(), extract(), observe(), and the agent loop.
• addedsentinel.clearPromptCache() — flush the prompt cache programmatically.
• addedIPromptCache interface exported for custom backends (Redis, SQLite, etc.).
• fixedSentinel.parallel() factory errors are now isolated per task — a browser launch failure no longer aborts remaining tasks.
• fixedextend() CDP session leak — calling extend() on the same page multiple times now detaches the previous session first.

Sentinel.parallel() — concurrent browser sessions with a worker pool, error isolation, and progress callbacks.

• addedSentinel.parallel(tasks, options) — runs N independent agent tasks in parallel, each in its own browser session. concurrency option limits simultaneous sessions (default: 3).
• addedonProgress callback — fires after each task with (completed, total, result).
• addedParallelTask, ParallelResult, ParallelOptions types exported.

sentinel.extend(page) — add AI capabilities to any existing Playwright Page object.

• addedsentinel.extend(page) — attaches act(), extract(), and observe() directly to any Playwright Page. Drop-in for existing Playwright projects.
• addedverbose: 3 — new debug level exposing chunk-processing stats and full LLM decision JSON per act() call.
• changedverbose: 1 now logs action summaries only. Reasoning moved to verbose: 2. Minor breaking change for consumers relying on reasoning at level 1.

Chunk-processing, Shadow DOM, and iframe support.

• addedfilterRelevantElements() — keyword-overlap scoring reduces elements sent to LLM on pages with 200+ interactive elements. maxElements option (default: 50).
• addedFull Shadow DOM support — parseDOMSnapshot() and parseFormElements() recursively pierce all shadow roots via queryShadowAll(). Covers Salesforce, ServiceNow, Lit, Polymer, Stencil.
• addediframe support — parseFrameElements() collects interactive elements from same-origin frames with coordinate offsets.

Intelligent error messages with structured diagnostic output and actionable tips.

• addedActionResult.attempts — structured array of every tried path (coordinate-click, vision-grounding, locator-fallback) with specific errors.
• addedContextual tip in result.message — outside viewport → scroll suggestion, timeout → overlay hint, all paths exhausted → rephrase or enable visionFallback.

Self-healing locators — cache successful element lookups, skip the LLM on repeated calls.

• addedlocatorCache option (false | true | string) — in-memory or file-persisted cache. On repeated act() calls with the same URL + instruction, Playwright uses the cached selector directly.
• addedAutomatic cache invalidation — if the cached element is gone, the entry is removed and the LLM path takes over.
• addedILocatorCache interface exported for custom backends (Redis, etc.).

Six bug fixes: stale DOM on retries, tab index corruption, elementCounter race, wrong Gemini model, token callback leak, MCP crash on browser failure.

• fixedstateParser.invalidateCache() now called at the start of every retry attempt — not just once before the loop.
• fixedcloseTab() now correctly decrements activePageIndex when a lower-index tab is closed.
• fixedelementCounter race condition in StateParser — now a local variable threaded through parallel parse() calls.
• fixedGeminiProvider.generateText() with systemInstruction now uses the constructor model, not process.env.GEMINI_VERSION.
• fixedonTokenUsage callback nulled out on close() to prevent TokenTracker from being held in memory.
• fixedAll 7 MCP tool handlers now wrapped in try-catch — browser failures return isError: true instead of crashing the server.

CLI tool, MCP server, and Playwright Test integration — all in one release.

• addedCLI — sentinel binary with 4 subcommands: run, act, extract, screenshot. Accepts --api-key, --headless, --model, --output, --url.
• addedMCP server — 8 tools exposed via stdio transport: sentinel_goto, _act, _extract, _observe, _run, _screenshot, _close, _token_usage.
• addedPlaywright Test fixture — @isoldex/sentinel/test exports test with ai fixture. sentinelOptions configurable globally in playwright.config.ts.

extract step type in AgentLoop, append action, token tracking, withRetry utility.

• breakingAgentLoop constructor now requires extractionEngine as second parameter. Only affects consumers constructing AgentLoop directly — sentinel.run() is unaffected.
• addedAgentResult.data — the planner can now issue extract steps mid-run. Structured data is returned in the final AgentResult.
• addedappend action type — appends text to an input without clearing existing content.
• addedToken usage tracking via onTokenUsage callback — all four providers fire it after every LLM call.
• addedwithRetry() utility — unified exponential backoff extracted from all four providers.
• fixeddomSettleTimeoutMs not forwarded to ActionEngine — now passed to all three waitForPageSettle call sites.

userDataDir — persistent browser profiles including IndexedDB (WhatsApp Web, PWAs).

• addeduserDataDir option — persists the full Chromium profile including IndexedDB and ServiceWorkers. Required for apps that use IndexedDB for auth (WhatsApp Web, etc.).

Native vision support for all LLM providers via analyzeImage().

• addedanalyzeImage() method added to all four providers (Gemini, OpenAI, Claude, Ollama). visionFallback: true now works with any vision-capable provider.
• changedDefault Gemini model updated to gemini-3-flash-preview.

Contextual button naming, off-screen enrichment, withTimeout on all actions, 4-strategy locator chain.

• addedContextual button naming — StateParser walks AOM ancestors to enrich generic labels like 'Select plan' with card context ('Kelag | Fixtarif | 17,40 cent/kWh: Select plan').
• addedwithTimeout wrapper on all actions — 10-second timeout prevents indefinite hangs.
• addedViewport bounds check before click + scrollIntoViewIfNeeded fallback.
• addedRadio/checkbox JS click fallback — handles inputs hidden via CSS by traversing to the closest label.
• added4-strategy locator chain: exact role+name → inexact role+name → CSS :has-text → plain text.
• changedMutationObserver DOM settle replaces networkidle — resolves after 300ms of DOM silence (cap: 3s).

Major release — Sentinel becomes a full AI agent framework.

• addedAutonomous Agent Loop — sentinel.run(goal) with Plan → Execute → Verify → Reflect cycle.
• addedVision Grounding — Gemini Vision fallback in act() via visionFallback option.
• addedMulti-LLM Provider System — GeminiProvider, OpenAIProvider, ClaudeProvider, OllamaProvider.
• addedMulti-Tab and Multi-Browser support (Chromium, Firefox, WebKit).
• addedSession Persistence — saveSession(), sessionPath option.
• addedRecord and Replay — startRecording(), stopRecording(), exportWorkflowAsCode(), replay().
• addedProxy and Stealth Mode — proxy option, humanLike delays, User-Agent rotation.
• addedEvent System — Sentinel extends EventEmitter, emits action, navigate, close.
• addedToken Tracking — getTokenUsage(), exportLogs().
• addedStructured Error Classes — SentinelError, ActionError, ExtractionError, NavigationError, AgentError, NotInitializedError.

Initial release — AOM-based browser automation with natural language actions.

• addedPlaywright-based browser automation (Chromium). AOM via CDP.
• addedsentinel.act(instruction) — click, fill, hover.
• addedsentinel.extract(instruction, schema) — Zod-typed structured extraction.
• addedsentinel.observe() — page observation via AOM.
• addedSemantic verification loop with automatic retry.
• addedGemini Flash / Pro integration, verbose logging levels.