From 2b1817898e0f3ed802fc36a5e539dd0c1a147754 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Sat, 27 Dec 2025 22:46:03 -0800
Subject: [PATCH 1/2] include goal in snapshot call

---
 src/agent.ts           |  9 +++++----
 src/snapshot.ts        |  2 ++
 tests/snapshot.test.ts | 28 ++++++++++++++++++++++++++++
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/src/agent.ts b/src/agent.ts
index 02287334..471cb995 100644
--- a/src/agent.ts
+++ b/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);
 
diff --git a/src/snapshot.ts b/src/snapshot.ts
index 19079cf9..72bfe89f 100644
--- a/src/snapshot.ts
+++ b/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,
diff --git a/tests/snapshot.test.ts b/tests/snapshot.test.ts
index a6615951..c5fe8191 100644
--- a/tests/snapshot.test.ts
+++ b/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
 });
 

From c71fce2ca21b112ba7d496065d440020786a9296 Mon Sep 17 00:00:00 2001
From: rcholic <ivytony@gmail.com>
Date: Sat, 27 Dec 2025 22:47:46 -0800
Subject: [PATCH 2/2] bump version

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 3a01239f..215978b0 100644
--- a/package.json
+++ b/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",