sentienceapi 0.93.0 → 0.95.0

package/README.md

@@ -1,6 +1,6 @@
 # Sentience TypeScript SDK
 
-**Semantic geometry grounding for deterministic, debuggable AI web agents with time-travel traces.**
+**Semantic snapshots and Jest-style assertions for reliable AI web agents with time-travel traces**
 
 ## 📦 Installation
 
@@ -19,6 +19,49 @@ npm install
 npm run build
 ```
 
+## Jest for AI Web Agent
+
+### Semantic snapshots and assertions that let agents act, verify, and know when they're done.
+
+Use `AgentRuntime` to add Jest-style assertions to your agent loops. Verify browser state, check task completion, and get clear feedback on what's working:
+
+```typescript
+import { SentienceBrowser, AgentRuntime, urlContains, exists, allOf } from 'sentienceapi';
+import { createTracer } from 'sentienceapi';
+import { Page } from 'playwright';
+
+// Create browser and tracer
+const browser = await SentienceBrowser.create({ apiKey: process.env.SENTIENCE_API_KEY });
+const tracer = await createTracer({ runId: 'my-run', uploadTrace: false });
+
+// Create browser adapter for AgentRuntime
+const browserAdapter = {
+  snapshot: async (_page: Page, options?: Record<string, any>) => {
+    return await browser.snapshot(options);
+  },
+};
+const runtime = new AgentRuntime(browserAdapter, browser.getPage(), tracer);
+
+// Navigate and take snapshot
+await browser.getPage().goto('https://example.com');
+runtime.beginStep('Verify page loaded');
+await runtime.snapshot();
+
+// Run assertions (Jest-style)
+runtime.assert(urlContains('example.com'), 'on_correct_domain');
+runtime.assert(exists('role=heading'), 'has_heading');
+runtime.assert(allOf([exists('role=button'), exists('role=link')]), 'has_interactive_elements');
+
+// Check task completion
+if (runtime.assertDone(exists("text~'Example'"), 'task_complete')) {
+  console.log('✅ Task completed!');
+}
+
+console.log(`Task done: ${runtime.isTaskDone}`);
+```
+
+**See example:** [examples/agent-runtime-verification.ts](examples/agent-runtime-verification.ts)
+
 ## 🚀 Quick Start: Choose Your Abstraction Level
 
 Sentience SDK offers **4 levels of abstraction** - choose based on your needs:
@@ -142,8 +185,6 @@ await browser.close();
 
 ---
 
-## 🆕 What's New (2026-01-06)
-
 ### Human-like Typing
 
 Add realistic delays between keystrokes to mimic human typing:

package/dist/asserts/expect.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Expectation builder for assertion DSL.
+ *
+ * This module provides the expect() builder that creates fluent assertions
+ * which compile to existing Predicate objects.
+ *
+ * Key classes:
+ * - ExpectBuilder: Fluent builder for element-based assertions
+ * - EventuallyConfig: Configuration for .eventually() retry logic
+ *
+ * The expect() function is the main entry point. It returns a builder that
+ * can be chained with matchers:
+ *     expect(E({ role: "button" })).toExist()
+ *     expect(E({ textContains: "Error" })).notToExist()
+ *     expect.textPresent("Welcome")
+ *
+ * All builders compile to Predicate functions compatible with AgentRuntime.assert().
+ */
+import { Predicate, AssertOutcome, AssertContext } from '../verification';
+import { ElementQuery, MultiQuery, MultiTextPredicate } from './query';
+/**
+ * Configuration for .eventually() retry logic.
+ */
+export interface EventuallyConfig {
+    /** Max time to wait (milliseconds, default 10000) */
+    timeout?: number;
+    /** Interval between retries (milliseconds, default 200) */
+    poll?: number;
+    /** Max number of retry attempts (default 3) */
+    maxRetries?: number;
+}
+/**
+ * Fluent builder for element-based assertions.
+ *
+ * Created by expect(E(...)) or expect(inDominantList().nth(k)).
+ *
+ * Methods return Predicate functions that can be passed to runtime.assert().
+ *
+ * @example
+ * expect(E({ role: "button" })).toExist()
+ * expect(E({ textContains: "Error" })).notToExist()
+ * expect(E({ role: "link" })).toBeVisible()
+ */
+export declare class ExpectBuilder {
+    private _query;
+    constructor(query: ElementQuery | MultiQuery | MultiTextPredicate);
+    /**
+     * Assert that at least one element matches the query.
+     *
+     * @returns Predicate function for use with runtime.assert()
+     *
+     * @example
+     * await runtime.assert(
+     *   expect(E({ role: "button", textContains: "Save" })).toExist(),
+     *   "save_button_exists"
+     * );
+     */
+    toExist(): Predicate;
+    /**
+     * Assert that NO elements match the query.
+     *
+     * Useful for asserting absence of error messages, loading indicators, etc.
+     *
+     * @returns Predicate function for use with runtime.assert()
+     *
+     * @example
+     * await runtime.assert(
+     *   expect(E({ textContains: "Error" })).notToExist(),
+     *   "no_error_message"
+     * );
+     */
+    notToExist(): Predicate;
+    /**
+     * Assert that element exists AND is visible (in_viewport=true, is_occluded=false).
+     *
+     * @returns Predicate function for use with runtime.assert()
+     *
+     * @example
+     * await runtime.assert(
+     *   expect(E({ textContains: "Checkout" })).toBeVisible(),
+     *   "checkout_button_visible"
+     * );
+     */
+    toBeVisible(): Predicate;
+    /**
+     * Assert that element's text contains the specified substring.
+     *
+     * @param text - Substring to search for (case-insensitive)
+     * @returns Predicate function for use with runtime.assert()
+     *
+     * @example
+     * await runtime.assert(
+     *   expect(inDominantList().nth(0)).toHaveTextContains("Show HN"),
+     *   "first_item_is_show_hn"
+     * );
+     */
+    toHaveTextContains(text: string): Predicate;
+}
+/**
+ * Main entry point for the assertion DSL.
+ *
+ * Use as a function to create element-based assertions:
+ *   expect(E({ role: "button" })).toExist()
+ *
+ * Use static methods for global assertions:
+ *   expect.textPresent("Welcome")
+ *   expect.noText("Error")
+ */
+export declare const expect: ((query: ElementQuery | MultiQuery | MultiTextPredicate) => ExpectBuilder) & {
+    textPresent: (text: string) => Predicate;
+    noText: (text: string) => Predicate;
+};
+/**
+ * Wrapper that adds retry logic to a predicate.
+ *
+ * Created by withEventually(). Provides an async evaluate() method
+ * that retries the predicate with fresh snapshots.
+ *
+ * Note: TypeScript uses milliseconds for timeout/poll.
+ */
+export declare class EventuallyWrapper {
+    private _predicate;
+    private _config;
+    constructor(predicate: Predicate, config?: EventuallyConfig);
+    /**
+     * Evaluate predicate with retry logic.
+     *
+     * @param ctx - Initial assertion context
+     * @param snapshotFn - Async function to take fresh snapshots
+     * @returns Promise resolving to AssertOutcome
+     */
+    evaluate(ctx: AssertContext, snapshotFn: () => Promise<AssertContext['snapshot']>): Promise<AssertOutcome>;
+    private sleep;
+    /** Get the configured timeout in milliseconds */
+    get timeout(): number;
+    /** Get the configured poll interval in milliseconds */
+    get poll(): number;
+    /** Get the configured max retries */
+    get maxRetries(): number;
+}
+/**
+ * Wrap a predicate with retry logic.
+ *
+ * This is the TypeScript API for .eventually(). Returns a wrapper
+ * that provides an async evaluate() method for use with the runtime.
+ *
+ * @param predicate - Predicate to wrap
+ * @param config - Retry configuration (timeout/poll in milliseconds)
+ * @returns EventuallyWrapper with async evaluate() method
+ *
+ * @example
+ * const wrapper = withEventually(
+ *   expect(E({ role: "button" })).toExist(),
+ *   { timeout: 5000, maxRetries: 10 }
+ * );
+ * const result = await wrapper.evaluate(ctx, runtime.snapshot);
+ */
+export declare function withEventually(predicate: Predicate, config?: EventuallyConfig): EventuallyWrapper;
+//# sourceMappingURL=expect.d.ts.map

package/dist/asserts/expect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect.d.ts","sourceRoot":"","sources":["../../src/asserts/expect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAOvE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoCD;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAiD;gBAEnD,KAAK,EAAE,YAAY,GAAG,UAAU,GAAG,kBAAkB;IAIjE;;;;;;;;;;OAUG;IACH,OAAO,IAAI,SAAS;IA+BpB;;;;;;;;;;;;OAYG;IACH,UAAU,IAAI,SAAS;IAiCvB;;;;;;;;;;OAUG;IACH,WAAW,IAAI,SAAS;IAgDxB;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;CA8C5C;AAqID;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,WACT,YAAY,GAAG,UAAU,GAAG,kBAAkB;wBAEhC,MAAM;mBACX,MAAM;CAExB,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,OAAO,CAA6B;gBAEhC,SAAS,EAAE,SAAS,EAAE,MAAM,GAAE,gBAAqB;IAS/D;;;;;;OAMG;IACG,QAAQ,CACZ,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,GACnD,OAAO,CAAC,aAAa,CAAC;IA8EzB,OAAO,CAAC,KAAK;IAIb,iDAAiD;IACjD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qCAAqC;IACrC,IAAI,UAAU,IAAI,MAAM,CAEvB;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAEjG"}