@predicatelabs/sdk 0.99.9

package/LICENSE

@@ -0,0 +1,24 @@
+# License
+
+This project is dual-licensed under your choice of either:
+
+* **MIT License** ([LICENSE-MIT](./LICENSE-MIT))
+* **Apache License 2.0** ([LICENSE-APACHE](./LICENSE-APACHE))
+
+## Choosing a License
+
+You may use this software under the terms of either license, at your option.
+
+### MIT License
+The MIT License is a permissive license that is short and to the point. It lets people do almost anything they want with your project, like making and distributing closed source versions.
+
+### Apache License 2.0
+The Apache License 2.0 is also a permissive license, similar to MIT, but it also provides an express grant of patent rights from contributors to users.
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you shall be dual-licensed as above, without any additional terms or conditions.
+
+---
+
+Copyright (c) 2025 Sentience Contributors

package/README.md

@@ -0,0 +1,252 @@
+# Predicate TypeScript SDK
+
+> **A verification & control layer for AI agents that operate browsers**
+
+Predicate is built for **AI agent developers** who already use Playwright / CDP / LangGraph and care about **flakiness, cost, determinism, evals, and debugging**.
+
+Often described as _Jest for Browser AI Agents_ - but applied to end-to-end agent runs (not unit tests).
+
+The core loop is:
+
+> **Agent → Snapshot → Action → Verification → Artifact**
+
+## What Predicate is
+
+- A **verification-first runtime** (`AgentRuntime`) for browser agents
+- Treats the browser as an adapter (Playwright / CDP); **`AgentRuntime` is the product**
+- A **controlled perception** layer (semantic snapshots; pruning/limits; lowers token usage by filtering noise from what models see)
+- A **debugging layer** (structured traces + failure artifacts)
+- Enables **local LLM small models (3B-7B)** for browser automation (privacy, compliance, and cost control)
+- Keeps vision models **optional** (use as a fallback when DOM/snapshot structure falls short, e.g. `<canvas>`)
+
+## What Predicate is not
+
+- Not a browser driver
+- Not a Playwright replacement
+- Not a vision-first agent framework
+
+## Install
+
+```bash
+npm install @predicatelabs/sdk
+npx playwright install chromium
+```
+
+## Naming migration (Predicate rebrand)
+
+Use the new `Predicate*` class names for all new code:
+
+- `PredicateBrowser`
+- `PredicateAgent`
+- `PredicateVisualAgent`
+- `PredicateDebugger`
+- `backends.PredicateContext`
+
+## Conceptual example (why this exists)
+
+- Steps are **gated by verifiable UI assertions**
+- If progress can’t be proven, the run **fails with evidence**
+- This is how you make runs **reproducible** and **debuggable**, and how you run evals reliably
+
+## Quickstart: a verification-first loop
+
+```ts
+import { PredicateBrowser, AgentRuntime } from '@predicatelabs/sdk';
+import { JsonlTraceSink, Tracer } from '@predicatelabs/sdk';
+import { exists, urlContains } from '@predicatelabs/sdk';
+import type { Page } from 'playwright';
+
+async function main(): Promise<void> {
+  const tracer = new Tracer('demo', new JsonlTraceSink('trace.jsonl'));
+
+  const browser = new PredicateBrowser();
+  await browser.start();
+  const page = browser.getPage();
+  if (!page) throw new Error('no page');
+
+  await page.goto('https://example.com');
+
+  // AgentRuntime needs a snapshot provider; PredicateBrowser.snapshot() does not depend on Page,
+  // so we wrap it to fit the runtime interface.
+  const runtime = new AgentRuntime(
+    { snapshot: async (_page: Page, options?: Record<string, any>) => browser.snapshot(options) },
+    page,
+    tracer
+  );
+
+  runtime.beginStep('Verify homepage');
+  await runtime.snapshot({ limit: 60 });
+
+  runtime.assert(urlContains('example.com'), 'on_domain', true);
+  runtime.assert(exists('role=heading'), 'has_heading');
+
+  runtime.assertDone(exists("text~'Example'"), 'task_complete');
+
+  await browser.close();
+}
+
+void main();
+```
+
+## PredicateDebugger: attach to your existing agent framework (sidecar mode)
+
+If you already have an agent loop (LangGraph, custom planner/executor), keep it and attach Predicate as a **verifier + trace layer**.
+
+Key idea: your agent still executes actions — Predicate **snapshots and verifies outcomes**.
+
+```ts
+import type { Page } from 'playwright';
+import { PredicateDebugger, Tracer, JsonlTraceSink, exists, urlContains } from '@predicatelabs/sdk';
+
+async function runExistingAgent(page: Page): Promise<void> {
+  const tracer = new Tracer('run-123', new JsonlTraceSink('trace.jsonl'));
+  const dbg = PredicateDebugger.attach(page, tracer);
+
+  await dbg.step('agent_step: navigate + verify', async () => {
+    // 1) Let your framework do whatever it does
+    await yourAgent.step();
+
+    // 2) Snapshot what the agent produced
+    await dbg.snapshot({ limit: 60 });
+
+    // 3) Verify outcomes (with bounded retries)
+    await dbg
+      .check(urlContains('example.com'), 'on_domain', true)
+      .eventually({ timeoutMs: 10_000 });
+    await dbg.check(exists('role=heading'), 'has_heading').eventually({ timeoutMs: 10_000 });
+  });
+}
+```
+
+## SDK-driven full loop (snapshots + actions)
+
+If you want Predicate to drive the loop end-to-end, you can use the SDK primitives directly: take a snapshot, select elements, act, then verify.
+
+```ts
+import { PredicateBrowser, snapshot, find, typeText, click, waitFor } from '@predicatelabs/sdk';
+
+async function loginExample(): Promise<void> {
+  const browser = new PredicateBrowser();
+  await browser.start();
+  const page = browser.getPage();
+  if (!page) throw new Error('no page');
+
+  await page.goto('https://example.com/login');
+
+  const snap = await snapshot(browser);
+  const email = find(snap, "role=textbox text~'email'");
+  const password = find(snap, "role=textbox text~'password'");
+  const submit = find(snap, "role=button text~'sign in'");
+  if (!email || !password || !submit) throw new Error('login form not found');
+
+  await typeText(browser, email.id, 'user@example.com');
+  await typeText(browser, password.id, 'password123');
+  await click(browser, submit.id);
+
+  const ok = await waitFor(browser, "role=heading text~'Dashboard'", 10_000);
+  if (!ok.found) throw new Error('login failed');
+
+  await browser.close();
+}
+```
+
+## Capabilities (lifecycle guarantees)
+
+### Controlled perception
+
+- **Semantic snapshots** instead of raw DOM dumps
+- **Pruning knobs** via `SnapshotOptions` (limit/filter)
+- Snapshot diagnostics that help decide when “structure is insufficient”
+
+### Constrained action space
+
+- Action primitives operate on **stable IDs / rects** derived from snapshots
+- Optional helpers for ordinality (“click the 3rd result”)
+
+### Verified progress
+
+- Predicates like `exists(...)`, `urlMatches(...)`, `isEnabled(...)`, `valueEquals(...)`
+- Fluent assertion DSL via `expect(...)`
+- Retrying verification via `runtime.check(...).eventually(...)`
+
+### Explained failure
+
+- JSONL trace events (`Tracer` + `JsonlTraceSink`)
+- Optional failure artifact bundles (snapshots, diagnostics, step timelines, frames/clip)
+- Deterministic failure semantics: when required assertions can’t be proven, the run fails with artifacts you can replay
+
+### Framework interoperability
+
+- Bring your own LLM and orchestration (LangGraph, custom loops)
+- Register explicit LLM-callable tools with `ToolRegistry`
+
+## ToolRegistry (LLM-callable tools)
+
+```ts
+import { ToolRegistry, registerDefaultTools } from '@predicatelabs/sdk';
+
+const registry = new ToolRegistry();
+registerDefaultTools(registry);
+const toolsForLLM = registry.llmTools();
+```
+
+## Permissions (avoid Chrome permission bubbles)
+
+Chrome permission prompts are outside the DOM and can be invisible to snapshots. Prefer setting a policy **before navigation**.
+
+```ts
+import { PredicateBrowser } from '@predicatelabs/sdk';
+import type { PermissionPolicy } from '@predicatelabs/sdk';
+
+const policy: PermissionPolicy = {
+  default: 'clear',
+  autoGrant: ['geolocation'],
+  geolocation: { latitude: 37.77, longitude: -122.41, accuracy: 50 },
+  origin: 'https://example.com',
+};
+
+// `permissionPolicy` is the last constructor argument; pass `keepAlive` right before it.
+const browser = new PredicateBrowser(
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  false,
+  policy
+);
+await browser.start();
+```
+
+If your backend supports it, you can also use ToolRegistry permission tools (`grant_permissions`, `clear_permissions`, `set_geolocation`) mid-run.
+
+## Downloads (verification predicate)
+
+```ts
+import { downloadCompleted } from '@predicatelabs/sdk';
+
+runtime.assert(downloadCompleted('report.csv'), 'download_ok', true);
+```
+
+## Debugging (fast)
+
+- **Manual driver CLI**:
+
+```bash
+npx predicate driver --url https://example.com
+```
+
+- **Verification + artifacts + debugging with time-travel traces (Predicate Studio demo)**:
+
+<video src="https://github.com/user-attachments/assets/7ffde43b-1074-4d70-bb83-2eb8d0469307" controls muted playsinline></video>
+
+If the video tag doesn’t render in your GitHub README view, use this link: [`sentience-studio-demo.mp4`](https://github.com/user-attachments/assets/7ffde43b-1074-4d70-bb83-2eb8d0469307)
+
+- **Predicate SDK Documentation**: https://predicatelabs.dev/docs

package/dist/actions.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Actions v1 - click, type, press
+ */
+import { IBrowser } from './protocols/browser-protocol';
+import { ActionResult, BBox } from './types';
+import { SnapshotOptions } from './snapshot';
+import { CursorPolicy } from './cursor-policy';
+export interface ClickRect {
+    x: number;
+    y: number;
+    w?: number;
+    width?: number;
+    h?: number;
+    height?: number;
+}
+/**
+ * Click an element by its ID
+ *
+ * Uses a hybrid approach: gets element bounding box from snapshot and calculates center,
+ * then uses Playwright's native mouse.click() for realistic event simulation.
+ * Falls back to JavaScript click if element not found in snapshot.
+ *
+ * @param browser - SentienceBrowser instance
+ * @param elementId - Element ID from snapshot
+ * @param useMouse - Use mouse simulation (default: true). If false, uses JavaScript click.
+ * @param takeSnapshot - Take snapshot after action (default: false)
+ * @returns ActionResult with success status, outcome, duration, and optional snapshot
+ *
+ * @example
+ * ```typescript
+ * const snap = await snapshot(browser);
+ * const button = find(snap, 'role=button');
+ * if (button) {
+ *   const result = await click(browser, button.id);
+ *   console.log(`Click ${result.success ? 'succeeded' : 'failed'}`);
+ * }
+ * ```
+ */
+export declare function click(browser: IBrowser, elementId: number, useMouse?: boolean, takeSnapshot?: boolean, cursorPolicy?: CursorPolicy): Promise<ActionResult>;
+/**
+ * Type text into an input element
+ *
+ * Focuses the element first, then types the text using Playwright's keyboard simulation.
+ *
+ * @param browser - SentienceBrowser instance
+ * @param elementId - Element ID from snapshot (must be a text input element)
+ * @param text - Text to type
+ * @param takeSnapshot - Take snapshot after action (default: false)
+ * @param delayMs - Delay between keystrokes in milliseconds for human-like typing (default: 0)
+ * @returns ActionResult with success status, outcome, duration, and optional snapshot
+ *
+ * @example
+ * ```typescript
+ * const snap = await snapshot(browser);
+ * const searchBox = find(snap, 'role=searchbox');
+ * if (searchBox) {
+ *   // Type instantly (default behavior)
+ *   await typeText(browser, searchBox.id, 'Hello World');
+ *
+ *   // Type with human-like delay (~10ms between keystrokes)
+ *   await typeText(browser, searchBox.id, 'Hello World', false, 10);
+ * }
+ * ```
+ */
+export declare function typeText(browser: IBrowser, elementId: number, text: string, takeSnapshot?: boolean, delayMs?: number): Promise<ActionResult>;
+/**
+ * Clear the value of an input/textarea element (best-effort).
+ */
+export declare function clear(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Ensure a checkbox/radio is checked (best-effort).
+ */
+export declare function check(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Ensure a checkbox/radio is unchecked (best-effort).
+ */
+export declare function uncheck(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Select an option in a <select> element by matching option value or label (best-effort).
+ */
+export declare function selectOption(browser: IBrowser, elementId: number, option: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Upload a local file via an <input type="file"> element (best-effort).
+ */
+export declare function uploadFile(browser: IBrowser, elementId: number, filePath: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Submit a form (best-effort) by clicking a submit control or calling requestSubmit().
+ */
+export declare function submit(browser: IBrowser, elementId: number, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Navigate back in history (best-effort).
+ */
+export declare function back(browser: IBrowser, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Scroll an element into view
+ *
+ * Scrolls the page so that the specified element is visible in the viewport.
+ * Uses the element registry to find the element and scrollIntoView() to scroll it.
+ *
+ * @param browser - SentienceBrowser instance
+ * @param elementId - Element ID from snapshot to scroll into view
+ * @param behavior - Scroll behavior: 'smooth' for animated scroll, 'instant' for immediate (default: 'smooth')
+ * @param block - Vertical alignment: 'start', 'center', 'end', 'nearest' (default: 'center')
+ * @param takeSnapshot - Take snapshot after action (default: false)
+ * @returns ActionResult with success status, outcome, duration, and optional snapshot
+ *
+ * @example
+ * ```typescript
+ * const snap = await snapshot(browser);
+ * const button = find(snap, 'role=button[name="Submit"]');
+ * if (button) {
+ *   // Scroll element into view with smooth animation
+ *   await scrollTo(browser, button.id);
+ *
+ *   // Scroll instantly to top of viewport
+ *   await scrollTo(browser, button.id, 'instant', 'start');
+ * }
+ * ```
+ */
+export declare function scrollTo(browser: IBrowser, elementId: number, behavior?: 'smooth' | 'instant' | 'auto', block?: 'start' | 'center' | 'end' | 'nearest', takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Press a keyboard key
+ *
+ * Simulates pressing a key using Playwright's keyboard API.
+ * Common keys: 'Enter', 'Escape', 'Tab', 'ArrowUp', 'ArrowDown', etc.
+ *
+ * @param browser - SentienceBrowser instance
+ * @param key - Key to press (e.g., 'Enter', 'Escape', 'Tab')
+ * @param takeSnapshot - Take snapshot after action (default: false)
+ * @returns ActionResult with success status, outcome, duration, and optional snapshot
+ *
+ * @example
+ * ```typescript
+ * // Press Enter after typing
+ * await typeText(browser, elementId, 'search query');
+ * await press(browser, 'Enter');
+ * ```
+ */
+export declare function press(browser: IBrowser, key: string, takeSnapshot?: boolean): Promise<ActionResult>;
+/**
+ * Send a sequence of key presses (e.g., "CMD+H", "CTRL+SHIFT+P").
+ */
+export declare function sendKeys(browser: IBrowser, sequence: string, takeSnapshot?: boolean, delayMs?: number): Promise<ActionResult>;
+/**
+ * Navigate to a search results page for the given query.
+ */
+export declare function search(browser: IBrowser, query: string, engine?: string, takeSnapshot?: boolean, snapshotOptions?: SnapshotOptions | undefined): Promise<ActionResult>;
+/**
+ * Click at the center of a rectangle using Playwright's native mouse simulation.
+ * This uses a hybrid approach: calculates center coordinates and uses mouse.click()
+ * for realistic event simulation (triggers hover, focus, mousedown, mouseup).
+ *
+ * @param browser - SentienceBrowser instance
+ * @param rect - Rectangle with x, y, w (or width), h (or height) keys, or BBox object
+ * @param highlight - Whether to show a red border highlight when clicking (default: true)
+ * @param highlightDuration - How long to show the highlight in seconds (default: 2.0)
+ * @param takeSnapshot - Whether to take snapshot after action
+ * @returns ActionResult
+ *
+ * @example
+ * ```typescript
+ * // Click using rect object
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 });
+ *
+ * // Click using BBox from element
+ * const snap = await snapshot(browser);
+ * const element = find(snap, "role=button");
+ * if (element) {
+ *   await clickRect(browser, {
+ *     x: element.bbox.x,
+ *     y: element.bbox.y,
+ *     w: element.bbox.width,
+ *     h: element.bbox.height
+ *   });
+ * }
+ *
+ * // Without highlight
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, false);
+ *
+ * // Custom highlight duration
+ * await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 }, true, 3.0);
+ * ```
+ */
+export declare function clickRect(browser: IBrowser, rect: ClickRect | BBox, highlight?: boolean, highlightDuration?: number, takeSnapshot?: boolean, cursorPolicy?: CursorPolicy): Promise<ActionResult>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}