@predicatelabs/sdk 0.99.9

package/dist/utils/zod.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodToJsonSchema = zodToJsonSchema;
+const zod_1 = require("zod");
+function unwrapSchema(schema) {
+    let current = schema;
+    let optional = false;
+    let nullable = false;
+    while (true) {
+        const typeName = current._def?.typeName;
+        if (typeName === zod_1.ZodFirstPartyTypeKind.ZodOptional) {
+            optional = true;
+            current = current._def.innerType;
+            continue;
+        }
+        if (typeName === zod_1.ZodFirstPartyTypeKind.ZodDefault) {
+            optional = true;
+            current = current._def.innerType;
+            continue;
+        }
+        if (typeName === zod_1.ZodFirstPartyTypeKind.ZodNullable) {
+            nullable = true;
+            current = current._def.innerType;
+            continue;
+        }
+        break;
+    }
+    return { schema: current, optional, nullable };
+}
+function zodToJsonSchema(schema) {
+    const { schema: base, nullable } = unwrapSchema(schema);
+    const typeName = base._def?.typeName;
+    let result;
+    switch (typeName) {
+        case zod_1.ZodFirstPartyTypeKind.ZodString:
+            result = { type: 'string' };
+            break;
+        case zod_1.ZodFirstPartyTypeKind.ZodNumber:
+            result = { type: 'number' };
+            break;
+        case zod_1.ZodFirstPartyTypeKind.ZodBoolean:
+            result = { type: 'boolean' };
+            break;
+        case zod_1.ZodFirstPartyTypeKind.ZodLiteral:
+            result = { const: base._def.value, type: typeof base._def.value };
+            break;
+        case zod_1.ZodFirstPartyTypeKind.ZodEnum:
+            result = { type: 'string', enum: base._def.values };
+            break;
+        case zod_1.ZodFirstPartyTypeKind.ZodArray:
+            result = { type: 'array', items: zodToJsonSchema(base._def.type) };
+            break;
+        case zod_1.ZodFirstPartyTypeKind.ZodObject: {
+            const shape = base._def.shape();
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(shape)) {
+                const { schema: inner, optional } = unwrapSchema(value);
+                properties[key] = zodToJsonSchema(inner);
+                if (!optional)
+                    required.push(key);
+            }
+            result = { type: 'object', properties, required };
+            break;
+        }
+        case zod_1.ZodFirstPartyTypeKind.ZodUnion:
+            result = {
+                anyOf: base._def.options.map((opt) => zodToJsonSchema(opt)),
+            };
+            break;
+        default:
+            result = {};
+            break;
+    }
+    if (nullable) {
+        return { anyOf: [result, { type: 'null' }] };
+    }
+    return result;
+}
+//# sourceMappingURL=zod.js.map

package/dist/utils/zod.js.map

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

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility functions for Sentience SDK
+ *
+ * @deprecated This file is being migrated to src/utils/ directory.
+ * Use imports from src/utils/ instead.
+ */
+export { saveStorageState } from './utils/browser';
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/utils.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Utility functions for Sentience SDK
+ *
+ * @deprecated This file is being migrated to src/utils/ directory.
+ * Use imports from src/utils/ instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveStorageState = void 0;
+// Re-export for backward compatibility
+var browser_1 = require("./utils/browser");
+Object.defineProperty(exports, "saveStorageState", { enumerable: true, get: function () { return browser_1.saveStorageState; } });
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,uCAAuC;AACvC,2CAAmD;AAA1C,2GAAA,gBAAgB,OAAA"}

package/dist/verification.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Verification primitives for agent assertion loops.
+ *
+ * This module provides assertion predicates and outcome types for runtime verification
+ * in agent loops. Assertions evaluate against the current browser state (snapshot/url)
+ * and record results into the trace.
+ *
+ * Key concepts:
+ * - AssertOutcome: Result of evaluating an assertion
+ * - AssertContext: Context provided to assertion predicates (snapshot, url, stepId)
+ * - Predicate: Callable that takes context and returns outcome
+ *
+ * @example
+ * ```typescript
+ * import { urlMatches, exists, AssertContext } from './verification';
+ *
+ * // Create predicates
+ * const onSearchPage = urlMatches(/\/s\?k=/);
+ * const resultsLoaded = exists("text~'Results'");
+ *
+ * // Evaluate against context
+ * const ctx: AssertContext = { snapshot, url: "https://example.com/s?k=shoes" };
+ * const outcome = onSearchPage(ctx);
+ * console.log(outcome.passed); // true
+ * ```
+ */
+import { Snapshot, QuerySelector } from './types';
+/**
+ * Result of evaluating an assertion predicate.
+ */
+export interface AssertOutcome {
+    /** Whether the assertion passed */
+    passed: boolean;
+    /** Human-readable explanation (especially useful when failed) */
+    reason: string;
+    /** Additional structured data for debugging/display */
+    details: Record<string, any>;
+}
+/**
+ * Context provided to assertion predicates.
+ *
+ * Provides access to current browser state without requiring
+ * the predicate to know about browser internals.
+ */
+export interface AssertContext {
+    /** Current page snapshot (may be null if not taken) */
+    snapshot: Snapshot | null;
+    /** Current page URL */
+    url: string | null;
+    /** Current step identifier (for trace correlation) */
+    stepId: string | null;
+    /** Optional: non-snapshot state signals for verification (e.g., downloads). */
+    downloads?: Array<Record<string, any>> | null;
+}
+/**
+ * Type alias for assertion predicates.
+ * A predicate takes context and returns an outcome.
+ */
+export type Predicate = (ctx: AssertContext) => AssertOutcome;
+/**
+ * Predicate that passes if a browser download has completed.
+ *
+ * Notes:
+ * - This relies on `AssertContext.downloads` being populated by the runtime/browser.
+ */
+export declare function downloadCompleted(filenameSubstring?: string): Predicate;
+/**
+ * Create a predicate that checks if current URL matches a regex pattern.
+ *
+ * @param pattern - Regular expression pattern or string to match against URL
+ * @returns Predicate function that evaluates URL matching
+ *
+ * @example
+ * ```typescript
+ * const pred = urlMatches(/\/search\?q=/);
+ * const ctx = { snapshot: null, url: "https://example.com/search?q=shoes", stepId: null };
+ * const outcome = pred(ctx);
+ * console.log(outcome.passed); // true
+ * ```
+ */
+export declare function urlMatches(pattern: string | RegExp): Predicate;
+/**
+ * Create a predicate that checks if current URL contains a substring.
+ *
+ * @param substring - String to search for in URL
+ * @returns Predicate function that evaluates URL containment
+ *
+ * @example
+ * ```typescript
+ * const pred = urlContains("/cart");
+ * const ctx = { snapshot: null, url: "https://example.com/cart/checkout", stepId: null };
+ * const outcome = pred(ctx);
+ * console.log(outcome.passed); // true
+ * ```
+ */
+export declare function urlContains(substring: string): Predicate;
+/**
+ * Create a predicate that checks if elements matching selector exist.
+ *
+ * Uses the SDK's query engine to find matching elements.
+ *
+ * @param selector - Semantic selector string (e.g., "role=button text~'Sign in'")
+ * @returns Predicate function that evaluates element existence
+ *
+ * @example
+ * ```typescript
+ * const pred = exists("text~'Results'");
+ * // Will check if snapshot contains elements with "Results" in text
+ * ```
+ */
+export declare function exists(selector: QuerySelector): Predicate;
+/**
+ * Create a predicate that checks that NO elements match the selector.
+ *
+ * Useful for asserting that error messages, loading spinners, etc. are gone.
+ *
+ * @param selector - Semantic selector string
+ * @returns Predicate function that evaluates element non-existence
+ *
+ * @example
+ * ```typescript
+ * const pred = notExists("text~'Loading'");
+ * // Will pass if no elements contain "Loading" text
+ * ```
+ */
+export declare function notExists(selector: QuerySelector): Predicate;
+/**
+ * Create a predicate that checks the number of matching elements.
+ *
+ * @param selector - Semantic selector string
+ * @param options - Count constraints
+ * @returns Predicate function that evaluates element count
+ *
+ * @example
+ * ```typescript
+ * const pred = elementCount("role=button", { minCount: 1, maxCount: 5 });
+ * // Will pass if 1-5 buttons found
+ * ```
+ */
+export declare function elementCount(selector: QuerySelector, options?: {
+    minCount?: number;
+    maxCount?: number;
+}): Predicate;
+/**
+ * Create a predicate that passes only if ALL sub-predicates pass.
+ *
+ * @param predicates - Predicate functions to combine with AND logic
+ * @returns Combined predicate
+ *
+ * @example
+ * ```typescript
+ * const pred = allOf(urlContains("/cart"), exists("text~'Checkout'"));
+ * // Will pass only if both conditions are true
+ * ```
+ */
+export declare function allOf(...predicates: Predicate[]): Predicate;
+/**
+ * Create a predicate that passes if ANY sub-predicate passes.
+ *
+ * @param predicates - Predicate functions to combine with OR logic
+ * @returns Combined predicate
+ *
+ * @example
+ * ```typescript
+ * const pred = anyOf(exists("text~'Success'"), exists("text~'Complete'"));
+ * // Will pass if either condition is true
+ * ```
+ */
+export declare function anyOf(...predicates: Predicate[]): Predicate;
+/**
+ * Create a predicate from a custom function.
+ *
+ * @param checkFn - Function that takes AssertContext and returns boolean
+ * @param label - Label for debugging/display
+ * @returns Predicate wrapping the custom function
+ *
+ * @example
+ * ```typescript
+ * const pred = custom(
+ *   (ctx) => ctx.snapshot !== null && ctx.snapshot.elements.length > 10,
+ *   "has_many_elements"
+ * );
+ * ```
+ */
+export declare function custom(checkFn: (ctx: AssertContext) => boolean, label?: string): Predicate;
+export declare function isEnabled(selector: QuerySelector): Predicate;
+export declare function isDisabled(selector: QuerySelector): Predicate;
+export declare function isChecked(selector: QuerySelector): Predicate;
+export declare function isUnchecked(selector: QuerySelector): Predicate;
+export declare function valueEquals(selector: QuerySelector, expected: string): Predicate;
+export declare function valueContains(selector: QuerySelector, substring: string): Predicate;
+export declare function isExpanded(selector: QuerySelector): Predicate;
+export declare function isCollapsed(selector: QuerySelector): Predicate;
+//# sourceMappingURL=verification.d.ts.map

package/dist/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../src/verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAUlD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,uBAAuB;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,aAAa,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAkBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAY9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAUxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAwBzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAwB5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,SAAS,CA0CX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,CAoB3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,CAwB3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,EACxC,KAAK,GAAE,MAAiB,GACvB,SAAS,CAiBX;AAMD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CA4B5D;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAmB7D;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAmB5D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAmB9D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAoBhF;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAoBnF;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAmB7D;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAmB9D"}