Merge pull request #62 from SentienceAPI/include_goal

include goal in snapshot call

Author: rcholic

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentienceapi",
-  "version": "0.90.0",
+  "version": "0.90.1",
   "description": "TypeScript SDK for Sentience AI Agent Browser Automation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/agent.ts

@@ -159,10 +159,11 @@ export class SentienceAgent {
         // 1. OBSERVE: Get refined semantic snapshot
         const startTime = Date.now();
 
-        const snapOpts = snapshotOptions || {};
-        if (!snapOpts.limit) {
-          snapOpts.limit = this.snapshotLimit;
-        }
+        const snapOpts = {
+          ...snapshotOptions,
+          goal: snapshotOptions?.goal ?? goal,
+          limit: snapshotOptions?.limit || this.snapshotLimit,
+        };
 
         const snap = await snapshot(this.browser, snapOpts);
 

src/snapshot.ts

@@ -18,6 +18,7 @@ export interface SnapshotOptions {
   use_api?: boolean; // Force use of server-side API if True, local extension if False
   save_trace?: boolean; // Save raw_elements to JSON for benchmarking/training
   trace_path?: string; // Path to save trace file (default: "trace_{timestamp}.json")
+  goal?: string; // Optional goal/task description for the snapshot
 }
 
 /**
@@ -165,6 +166,7 @@ async function snapshotViaApi(
     raw_elements: rawResult.raw_elements || [],  // Raw data needed for server processing
     url: rawResult.url || '',
     viewport: rawResult.viewport,
+    goal: options.goal,  // Optional goal/task description
     options: {
       limit: options.limit,
       filter: options.filter,

tests/snapshot.test.ts

@@ -45,5 +45,33 @@ describe('Snapshot', () => {
       await browser.close();
     }
   }, 60000); // 60 seconds - browser startup can be slow
+
+  it('should accept goal parameter', async () => {
+    const browser = await createTestBrowser();
+
+    try {
+      await browser.getPage().goto('https://example.com');
+      await browser.getPage().waitForLoadState('networkidle');
+
+      // Test snapshot with goal
+      const snap = await snapshot(browser, { goal: 'Find the main heading' });
+
+      expect(snap.status).toBe('success');
+      expect(snap.url).toContain('example.com');
+      expect(snap.elements.length).toBeGreaterThan(0);
+
+      // Verify snapshot works normally with goal parameter
+      expect(snap.elements[0].id).toBeGreaterThanOrEqual(0);
+      if (snap.elements.length > 0) {
+        const element = snap.elements[0];
+        expect(element.bbox.x).toBeGreaterThanOrEqual(0);
+        expect(element.bbox.y).toBeGreaterThanOrEqual(0);
+        expect(element.bbox.width).toBeGreaterThan(0);
+        expect(element.bbox.height).toBeGreaterThan(0);
+      }
+    } finally {
+      await browser.close();
+    }
+  }, 60000); // 60 seconds - browser startup can be slow
 });