Documentation

npm install @isoldex/sentinel playwright
npx playwright install chromium

import { Sentinel, z } from '@isoldex/sentinel';

const sentinel = new Sentinel({ apiKey: process.env.GEMINI_API_KEY });
await sentinel.init();
await sentinel.goto('https://news.ycombinator.com');

// Extract structured data
const data = await sentinel.extract('Get the top 3 stories', z.object({
  stories: z.array(z.object({
    title: z.string(),
    points: z.number(),
  }))
}));

// Natural language actions
await sentinel.act('Click on the "new" link in the header');
await sentinel.act('Fill "hello@example.com" into the email field');

await sentinel.close();

// Basic click / fill / hover
await sentinel.act('Click the login button');
await sentinel.act('Fill "user@example.com" into the email field');
await sentinel.act('Hover over the profile menu');

// All supported action types
await sentinel.act('Select "Germany" from the country dropdown');
await sentinel.act('Press Enter');
await sentinel.act('Double-click the product image');
await sentinel.act('Right-click the file');
await sentinel.act('Scroll down');
await sentinel.act('Scroll up');
await sentinel.act('Scroll to the footer');
await sentinel.act('Append " (urgent)" to the subject line');

// Variable interpolation
await sentinel.act('Fill %email% into the email field', {
  variables: { email: 'user@example.com' },
});

// Custom retry count
await sentinel.act('Click the submit button', { retries: 5 });

import { Sentinel, z } from '@isoldex/sentinel';

// Zod schema — TypeScript type is inferred automatically
const result = await sentinel.extract(
  'Get all product names and prices',
  z.object({
    products: z.array(z.object({
      name:  z.string(),
      price: z.number(),
    }))
  })
);
// result.products is typed as { name: string; price: number }[]

// Raw JSON Schema also works
const result2 = await sentinel.extract('Get the page title', {
  type: 'object',
  properties: { title: { type: 'string' } },
});

// All interactive elements on the page
const elements = await sentinel.observe();

// Filtered by natural language hint
const loginElements = await sentinel.observe('Find login-related elements');

// Returns ObserveResult[]
// [{ description: 'Login button', role: 'button', ... }, ...]

const result = await sentinel.run(
  'Go to amazon.de, search for "mechanical keyboard under 100 euros", extract top 5',
  {
    maxSteps: 20,
    onStep: (event) => {
      console.log(`Step ${event.stepNumber} [${event.type}]: ${event.instruction}`);
      console.log(`  Reasoning: ${event.reasoning}`);
    },
  }
);

console.log(result.success);       // boolean
console.log(result.goalAchieved);  // boolean — final LLM reflection check
console.log(result.totalSteps);    // number of steps executed
console.log(result.message);       // human-readable summary
console.log(result.data);          // structured data extracted during the run
console.log(result.selectors);     // { searchField: '#twotabsearchtextbox', ... }
console.log(result.history);       // AgentStepEvent[] — full step-by-step log

const results = await Sentinel.parallel(
  [
    { url: 'https://amazon.de', goal: 'Find cheapest laptop' },
    { url: 'https://ebay.de',   goal: 'Find cheapest laptop' },
    { url: 'https://otto.de',   goal: 'Find cheapest laptop' },
  ],
  {
    apiKey: process.env.GEMINI_API_KEY,
    concurrency: 3,
    onProgress: (done, total, result) => {
      console.log(`${done}/${total}: ${result.url} — ${result.message}`);
    },
  }
);

// Results in input order regardless of completion order
// Error in one task never affects the others

// Open a new tab
const tabIndex = await sentinel.newTab('https://google.com');

// Switch the active tab
await sentinel.switchTab(0);
await sentinel.switchTab(tabIndex);

// Close a tab
await sentinel.closeTab(tabIndex);

// Number of open tabs
console.log(sentinel.tabCount);

// First run: log in, then save the session
await sentinel.goto('https://github.com/login');
await sentinel.act('Fill "myuser" into the username field');
await sentinel.act('Fill "mypassword" into the password field');
await sentinel.act('Click the sign in button');
await sentinel.saveSession('./sessions/github.json');

// Subsequent runs: session is restored automatically
const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,
  sessionPath: './sessions/github.json', // loaded on init()
});
await sentinel.init();
await sentinel.goto('https://github.com'); // already authenticated

// Start recording
sentinel.startRecording('checkout-flow');

await sentinel.goto('https://shop.example.com');
await sentinel.act('Click the first product');
await sentinel.act('Click Add to Cart');
await sentinel.act('Proceed to checkout');

// Stop and get the workflow
const workflow = sentinel.stopRecording();

// Export as TypeScript source code
const code = sentinel.exportWorkflowAsCode(workflow);
console.log(code); // ready-to-run TypeScript

// Export as JSON
const json = sentinel.exportWorkflowAsJSON(workflow);

// Replay the recorded workflow
await sentinel.replay(workflow);

const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,
  visionFallback: true, // activates vision grounding
});

// Takes a PNG screenshot → Buffer
const png = await sentinel.screenshot();

// Natural language description of the current page
const description = await sentinel.describeScreen();
console.log(description);
// "The page shows an Amazon product listing with a laptop card..."

// Vision grounding also activates automatically inside act()
// when AOM cannot locate the target element — no extra code needed.

const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,

  // Self-healing locators — cache successful element → selector mappings
  locatorCache: './sentinel-locators.json', // file-persisted (or: true for in-memory)

  // Prompt cache — cache LLM responses by prompt hash
  promptCache: './sentinel-prompts.json',   // file-persisted (or: true for in-memory)
});

// Flush the prompt cache programmatically (e.g. between test runs)
sentinel.clearPromptCache();

// Custom cache backends (e.g. Redis for distributed test runs)
import type { ILocatorCache, CachedLocator } from '@isoldex/sentinel';

class RedisLocatorCache implements ILocatorCache {
  get(url: string, instruction: string): CachedLocator | undefined { /* ... */ }
  set(url: string, instruction: string, entry: CachedLocator): void { /* ... */ }
  invalidate(url: string, instruction: string): void { /* ... */ }
}

import { Sentinel, RoundRobinProxyProvider, WebshareProxyProvider } from '@isoldex/sentinel';

const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,

  // Bézier mouse curves + per-action delays (80–200 ms) + human keystroke timing
  humanLike: true,

  // Static proxy
  proxy: { server: 'http://proxy.example.com:8080', username: 'u', password: 'p' },

  // — OR — round-robin through a list
  proxy: new RoundRobinProxyProvider([
    { server: 'http://p1:8080' },
    { server: 'http://p2:8080' },
  ]),

  // — OR — Webshare API with automatic rotation
  proxy: new WebshareProxyProvider({ apiKey: process.env.WEBSHARE_KEY! }),
});
// User-Agent rotation is automatic — no config needed.

import { chromium } from 'playwright';
import { Sentinel } from '@isoldex/sentinel';

const browser = await chromium.launch();
const page    = await browser.newPage();

const sentinel = new Sentinel({ apiKey: process.env.GEMINI_API_KEY });

// Attach Sentinel capabilities to any existing Playwright Page
await sentinel.extend(page);

// Now use act/extract/observe directly on the page object
await page.goto('https://example.com');
await page.act('Click the login button');

const data = await page.extract('Get the page title', z.object({
  title: z.string(),
}));

// After sentinel.run() — selectors for all act() steps
const result = await sentinel.run('Login with test@example.com');

console.log(result.selectors);
// {
//   clickLoginButton:  '[data-testid="login-btn"]',
//   fillEmailField:    '#email',
//   fillPasswordField: '[name="password"]',
// }

// Copy directly into Playwright tests — no DevTools digging
import { test, expect } from '@playwright/test';
test('login', async ({ page }) => {
  await page.click('[data-testid="login-btn"]');
});

// Single act() also exposes the selector
const r = await sentinel.act('Click the search field');
console.log(r.selector); // 'input[aria-label="Search"]'

// Event system (Sentinel extends EventEmitter)
sentinel.on('action', (event) => {
  console.log('Action:', event.instruction, event.result);
});

sentinel.on('navigate', (event) => {
  console.log('Navigated to:', event.url);
});

sentinel.on('close', () => {
  console.log('Browser closed');
});

// Direct Playwright access
const page    = sentinel.page;
const context = sentinel.context;

// Token tracking
const usage = sentinel.getTokenUsage();
console.log(usage);
// {
//   totalInputTokens: 9800,
//   totalOutputTokens: 2600,
//   totalTokens: 12400,
//   estimatedCostUsd: 0.00093,
//   entries: [...],
// }

// Export full log as JSON
sentinel.exportLogs('./logs/session.json');

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
  metricReader: new PrometheusExporter({ port: 9464 }),
});
sdk.start(); // must be called BEFORE new Sentinel(...)

const sentinel = new Sentinel({ apiKey: process.env.GEMINI_API_KEY });
// All act() / extract() / run() calls now emit spans and metrics automatically

import { test, expect } from '@isoldex/sentinel/test';
import { z } from 'zod';

test('completes checkout flow', async ({ ai, page }) => {
  await ai.goto('https://shop.example.com');
  await ai.act('Click the first product');
  await ai.act('Click Add to Cart');
  await ai.act('Proceed to checkout');

  const order = await ai.extract<{ total: string; items: number }>(
    'Get the order total and item count',
    z.object({ total: z.string(), items: z.number() })
  );

  expect(order.items).toBeGreaterThan(0);
  console.log('Token cost:', ai.getTokenUsage().estimatedCostUsd);
});

# Run an autonomous agent
npx @isoldex/sentinel run "Search for mechanical keyboards" \
  --url https://amazon.de \
  --output result.json

# Perform a single action
npx @isoldex/sentinel act "Click the login button" \
  --url https://example.com

# Extract structured data
npx @isoldex/sentinel extract "Get all product names and prices" \
  --url https://shop.example.com \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}'

# Take a screenshot
npx @isoldex/sentinel screenshot \
  --url https://example.com \
  --output page.png

import {
  SentinelError,
  ActionError,
  ExtractionError,
  NavigationError,
  AgentError,
  NotInitializedError,
} from '@isoldex/sentinel';

try {
  await sentinel.act('Click the submit button');
} catch (err) {
  if (err instanceof ActionError) {
    console.error(err.message, err.code, err.context);
    // code: "ACTION_FAILED"
  }
}

// Non-throwing alternative — check result.success
const result = await sentinel.act('Click checkout');
if (!result.success) {
  // result.message has the full diagnostic
  // result.attempts has each tried path
}