modjules 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # modjules - the agent-ready SDK for Jules
 
-> **Disclaimer:** This is a 100% total, absolute, **just-for-fun** prototype.
+> Status: Useful tool but still experimental. Supported and moving fast to improve.
 
 ## Making Jules Agent-Ready
 
@@ -59,7 +59,7 @@ Process multiple items in parallel with `jules.all()`. This method is designed t
 ```javascript
 const todos = ['Fix login bug', 'Update README', 'Refactor tests'];
 
-// Processes items concurrently (default: 4 at a time)
+// Processes items concurrently (default: 3 at a time)
 const sessions = await jules.all(todos, (task) => ({
   prompt: task,
   source: { github: 'user/repo', branch: 'main' },
@@ -121,16 +121,20 @@ const session = await jules.session({
 
 When used in a browser environment (e.g., in a web application bundled with Vite, Webpack, or Rollup), the SDK automatically uses a browser-specific implementation that leverages IndexedDB for storage. This allows your web application to maintain session state locally.
 
-> **Warning:** Never expose your `JULES_API_KEY` in a production or public-facing application. The browser module is designed for trusted client environments like Electron apps or websites running exclusively on a local machine.
+> **TEST ONLY DO NOT USE IN PRODUCTION:** The browser module is designed for testing and prototyping only. Never expose your `JULES_API_KEY` in a production application.
 
-To use the browser version, you can explicitly import it:
+To use the browser version, you can explicitly import it and must configure it with the test-only API key option:
 
 ```typescript
 // Explicitly import the browser-optimized version
 import { jules } from 'modjules/browser';
 
-// The rest of your code remains the same
-const session = await jules.session({
+// Initialize with the test-only option
+const testJules = jules.with({
+  apiKey_TEST_ONLY_DO_NOT_USE_IN_PRODUCTION: '...',
+});
+
+const session = await testJules.session({
   prompt: 'Refactor the user authentication module.',
   source: { github: 'your-org/your-repo', branch: 'develop' },
 });

package/dist/activities/client.d.ts

@@ -24,9 +24,52 @@ export declare class DefaultActivityClient implements ActivityClient {
     private network;
     constructor(storage: ActivityStorage, network: NetworkClient);
     /**
-     * Returns an async iterable of all activities stored locally.
+     * Re-hydrates plain artifact objects from storage into rich class instances.
+     * JSON serialization loses class information (methods), so we need to restore it.
+     *
+     * **Behavior:**
+     * - Iterates through artifacts in an activity.
+     * - If an artifact is a plain object (not a class instance), it's re-instantiated.
+     * - Handles backward compatibility: if an artifact is already a class instance, it's skipped.
+     *
+     * @param activity The activity from storage, potentially with plain artifacts.
+     * @returns The same activity with its artifacts guaranteed to be class instances.
+     */
+    private _hydrateActivityArtifacts;
+    /**
+     * Returns an async iterable of all activities.
+     *
+     * **Behavior:**
+     * - Always syncs new activities from the network first (via hydrate).
+     * - Then yields all activities from local storage.
+     *
+     * This ensures callers always get the complete, up-to-date history
+     * rather than potentially stale cached data.
      */
     history(): AsyncIterable<Activity>;
+    /**
+     * Fetches all activities from the network and caches them.
+     * Used to populate an empty cache.
+     * @internal
+     */
+    private fetchAndCacheAll;
+    /**
+     * Syncs new activities from the network to local cache.
+     *
+     * **Optimization Strategy:**
+     * Activities are immutable - once downloaded, they never change.
+     * We use the Jules API's pageToken (nanosecond timestamp) to fetch
+     * only activities newer than our latest cached one.
+     *
+     * **Behavior:**
+     * - Empty cache: Fetches all activities (no pageToken)
+     * - Has cached activities: Constructs pageToken from latest createTime,
+     *   fetches only newer activities
+     * - Frozen session (> 30 days): Skips API call entirely
+     *
+     * @returns The number of new activities synced.
+     */
+    hydrate(): Promise<number>;
     /**
      * Returns an async iterable of new activities from the network.
      * This method polls the network and updates the local storage.

package/dist/activities/types.d.ts

@@ -14,6 +14,7 @@ export interface SelectOptions {
     before?: string;
     type?: string;
     limit?: number;
+    order?: 'asc' | 'desc';
 }
 /**
  * Interface for managing session activities.
@@ -53,4 +54,10 @@ export interface ActivityClient {
      * NETWORK GET: Fetches a specific activity from the network and caches it.
      */
     get(activityId: string): Promise<Activity>;
+    /**
+     * NETWORK SYNC: Fetches all activities from the network and caches them.
+     * Useful when you suspect the cache is stale.
+     * @returns The number of activities synced.
+     */
+    hydrate(): Promise<number>;
 }

package/dist/activity/summary.d.ts

@@ -0,0 +1,7 @@
+import { Activity, ActivitySummary } from '../types.js';
+/**
+ * Creates a concise summary for an activity.
+ * @param activity The activity to summarize.
+ * @returns A summary of the activity.
+ */
+export declare function toSummary(activity: Activity): ActivitySummary;

package/dist/api.d.ts

@@ -1,12 +1,30 @@
+import { ProxyConfig } from './types.js';
+export type RateLimitRetryConfig = {
+    maxRetryTimeMs: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
 export type ApiClientOptions = {
     apiKey: string | undefined;
     baseUrl: string;
     requestTimeoutMs: number;
+    proxy?: ProxyConfig;
+    rateLimitRetry?: Partial<RateLimitRetryConfig>;
+};
+export type HandshakeContext = {
+    intent: 'create';
+    sessionConfig: any;
+} | {
+    intent: 'resume';
+    sessionId: string;
 };
 export type ApiRequestOptions = {
     method?: 'GET' | 'POST';
     body?: Record<string, unknown>;
-    params?: Record<string, string>;
+    query?: Record<string, any>;
+    headers?: Record<string, string>;
+    handshake?: HandshakeContext;
+    _isRetry?: boolean;
 };
 /**
  * A simple internal API client to handle HTTP requests to the Jules API.
@@ -16,6 +34,18 @@ export declare class ApiClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly requestTimeoutMs;
+    private readonly proxy?;
+    private readonly rateLimitConfig;
+    private capabilityToken;
+    private handshakePromise;
     constructor(options: ApiClientOptions);
     request<T>(endpoint: string, options?: ApiRequestOptions): Promise<T>;
+    /**
+     * Ensures we have a valid Capability Token.
+     * If not, performs the Handshake.
+     */
+    private ensureToken;
+    private performHandshake;
+    private resolveUrl;
+    private fetchWithTimeout;
 }

package/dist/artifacts.d.ts

@@ -1,4 +1,4 @@
-import { RestMediaArtifact, RestBashOutputArtifact } from './types.js';
+import { RestMediaArtifact, RestBashOutputArtifact, GitPatch, ParsedChangeSet } from './types.js';
 import { Platform } from './platform/types.js';
 /**
  * Represents a media artifact (e.g. image) produced by an activity.
@@ -52,3 +52,24 @@ export declare class BashArtifact {
      */
     toString(): string;
 }
+/**
+ * Represents a set of code changes (unified diff) produced by an activity.
+ * Provides a helper method to parse the diff into structured data.
+ */
+export declare class ChangeSetArtifact {
+    readonly type: "changeSet";
+    readonly source: string;
+    readonly gitPatch: GitPatch;
+    constructor(source: string, gitPatch: GitPatch);
+    /**
+     * Parses the unified diff and returns structured file change information.
+     *
+     * **Data Transformation:**
+     * - Extracts file paths from diff headers.
+     * - Determines change type (created/modified/deleted) from /dev/null markers.
+     * - Counts additions (+) and deletions (-) in hunks.
+     *
+     * @returns Parsed diff with file paths, change types, and line counts.
+     */
+    parsed(): ParsedChangeSet;
+}

package/dist/browser.d.ts

@@ -1,4 +1,12 @@
-import { JulesClient } from './types.js';
+import { JulesClient, JulesOptions } from './types.js';
+/**
+ * Connects to the Jules service with the provided configuration.
+ * Acts as a factory method for creating a new client instance.
+ *
+ * @param options Configuration options for the client.
+ * @returns A new JulesClient instance.
+ */
+export declare function connect(options?: JulesOptions): JulesClient;
 /**
  * The main entry point for the Jules SDK for browser environments.
  * This is a pre-initialized client that can be used immediately with default settings.

package/dist/browser.mjs

@@ -0,0 +1,304 @@
+import { J as JulesClientImpl, a as MemorySessionStorage } from "./memory-DE2Wujcu.js";
+import { A, I, d, e, b, c, f, h, i, j } from "./memory-DE2Wujcu.js";
+import { openDB } from "idb";
+const DB_NAME$1 = "jules-activities";
+const STORE_NAME = "activities";
+class BrowserStorage {
+  sessionId;
+  dbPromise = null;
+  constructor(sessionId) {
+    this.sessionId = sessionId;
+  }
+  getDb() {
+    if (!this.dbPromise) {
+      this.dbPromise = openDB(DB_NAME$1, 2, {
+        upgrade(db, oldVersion, newVersion, transaction) {
+          if (oldVersion < 1) {
+            if (!db.objectStoreNames.contains(STORE_NAME)) {
+              const store = db.createObjectStore(STORE_NAME, {
+                keyPath: "id"
+              });
+              store.createIndex("sessionTimestamp", [
+                "sessionId",
+                "createTime"
+              ]);
+            }
+          }
+          if (!db.objectStoreNames.contains("artifacts")) {
+            const store = db.createObjectStore("artifacts", {
+              keyPath: "filepath"
+            });
+            store.createIndex("activityId", "activityId");
+          }
+        }
+      });
+    }
+    return this.dbPromise;
+  }
+  /**
+   * Initializes the storage.
+   *
+   * **Side Effects:**
+   * - Opens an IndexedDB connection.
+   * - Upgrades the database schema to v2 if necessary (creating object stores).
+   */
+  async init() {
+    await this.getDb();
+  }
+  /**
+   * Closes the storage connection.
+   */
+  async close() {
+    if (this.dbPromise) {
+      const db = await this.dbPromise;
+      db.close();
+      this.dbPromise = null;
+    }
+  }
+  /**
+   * Appends an activity to IndexedDB.
+   *
+   * **Side Effects:**
+   * - Adds a `sessionId` field to the activity for indexing.
+   * - Writes the modified activity to the `activities` object store.
+   */
+  async append(activity) {
+    const db = await this.getDb();
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    const store = tx.objectStore(STORE_NAME);
+    const storableActivity = { ...activity, sessionId: this.sessionId };
+    await store.put(storableActivity);
+    await tx.done;
+  }
+  /**
+   * Retrieves an activity by ID.
+   */
+  async get(activityId) {
+    const db = await this.getDb();
+    const activity = await db.get(STORE_NAME, activityId);
+    if (activity) {
+      delete activity.sessionId;
+    }
+    return activity;
+  }
+  /**
+   * Retrieves the latest activity for the current session.
+   *
+   * **Logic:**
+   * - Uses the `sessionTimestamp` index to query efficiently.
+   * - Opens a cursor in 'prev' direction to find the last entry first.
+   */
+  async latest() {
+    const db = await this.getDb();
+    const tx = db.transaction(STORE_NAME, "readonly");
+    const store = tx.objectStore(STORE_NAME);
+    const index = store.index("sessionTimestamp");
+    const range = IDBKeyRange.bound(
+      [this.sessionId, ""],
+      [this.sessionId, (/* @__PURE__ */ new Date(864e13)).toISOString()]
+    );
+    const cursor = await index.openCursor(range, "prev");
+    if (!cursor) {
+      return void 0;
+    }
+    const activity = cursor.value;
+    if (activity) {
+      delete activity.sessionId;
+    }
+    return activity;
+  }
+  /**
+   * Yields all activities for the current session.
+   */
+  async *scan() {
+    const db = await this.getDb();
+    const tx = db.transaction(STORE_NAME, "readonly");
+    const store = tx.objectStore(STORE_NAME);
+    const index = store.index("sessionTimestamp");
+    const range = IDBKeyRange.bound(
+      [this.sessionId, ""],
+      [this.sessionId, (/* @__PURE__ */ new Date(864e13)).toISOString()]
+    );
+    let cursor = await index.openCursor(range, "next");
+    while (cursor) {
+      const activity = cursor.value;
+      if (activity) {
+        delete activity.sessionId;
+      }
+      yield activity;
+      cursor = await cursor.continue();
+    }
+  }
+}
+const __vite_import_meta_env__ = { "BASE_URL": "/", "DEV": false, "MODE": "production", "PROD": true, "SSR": false };
+const DB_NAME = "jules-activities";
+const ARTIFACTS_STORE_NAME = "artifacts";
+const ACTIVITIES_STORE_NAME = "activities";
+class BrowserPlatform {
+  dbPromise = null;
+  getDb() {
+    if (!this.dbPromise) {
+      this.dbPromise = openDB(DB_NAME, 2, {
+        upgrade(db, oldVersion, newVersion, transaction) {
+          if (!db.objectStoreNames.contains(ACTIVITIES_STORE_NAME)) {
+            const store = db.createObjectStore(ACTIVITIES_STORE_NAME, {
+              keyPath: "id"
+            });
+            store.createIndex("sessionTimestamp", ["sessionId", "createTime"]);
+          }
+          if (!db.objectStoreNames.contains(ARTIFACTS_STORE_NAME)) {
+            const store = db.createObjectStore(ARTIFACTS_STORE_NAME, {
+              keyPath: "filepath"
+            });
+            store.createIndex("activityId", "activityId");
+          }
+        }
+      });
+    }
+    return this.dbPromise;
+  }
+  /**
+   * Saves a file to IndexedDB.
+   *
+   * **Data Transformation:**
+   * - Decodes base64 data into a `Blob`.
+   *
+   * **Side Effects:**
+   * - Stores the blob in the `artifacts` object store.
+   * - Associates the file with the `activityId` (if provided).
+   *
+   * @throws {Error} If the encoding is not 'base64'.
+   */
+  async saveFile(filepath, data, encoding, activityId) {
+    if (encoding !== "base64") {
+      throw new Error(`Unsupported encoding for browser saveFile: ${encoding}`);
+    }
+    const db = await this.getDb();
+    const blob = this.base64ToBlob(data);
+    await db.put(ARTIFACTS_STORE_NAME, {
+      filepath,
+      blob,
+      activityId,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  async sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  createDataUrl(data, mimeType) {
+    return `data:${mimeType};base64,${data}`;
+  }
+  base64ToBlob(data, mimeType) {
+    const byteCharacters = atob(data);
+    const byteNumbers = new Array(byteCharacters.length);
+    for (let i2 = 0; i2 < byteCharacters.length; i2++) {
+      byteNumbers[i2] = byteCharacters.charCodeAt(i2);
+    }
+    const byteArray = new Uint8Array(byteNumbers);
+    return new Blob([byteArray], mimeType ? { type: mimeType } : void 0);
+  }
+  async fetch(input, init) {
+    const res = await window.fetch(input, init);
+    return {
+      ok: res.ok,
+      status: res.status,
+      json: () => res.json(),
+      text: () => res.text()
+    };
+  }
+  crypto = {
+    randomUUID: () => self.crypto.randomUUID(),
+    async sign(text, secret) {
+      const enc = new TextEncoder();
+      const key = await window.crypto.subtle.importKey(
+        "raw",
+        enc.encode(secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"]
+      );
+      const signature = await window.crypto.subtle.sign(
+        "HMAC",
+        key,
+        enc.encode(text)
+      );
+      return this.arrayBufferToBase64Url(signature);
+    },
+    async verify(text, signature, secret) {
+      const expected = await this.sign(text, secret);
+      return expected === signature;
+    },
+    // Helper for Base64URL encoding in browser
+    arrayBufferToBase64Url(buffer) {
+      const bytes = new Uint8Array(buffer);
+      let binary = "";
+      for (let i2 = 0; i2 < bytes.byteLength; i2++) {
+        binary += String.fromCharCode(bytes[i2]);
+      }
+      return window.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    }
+  };
+  encoding = {
+    base64Encode: (text) => {
+      const encoder = new TextEncoder();
+      const bytes = encoder.encode(text);
+      let binary = "";
+      for (let i2 = 0; i2 < bytes.length; i2++) {
+        binary += String.fromCharCode(bytes[i2]);
+      }
+      return window.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    },
+    base64Decode: (text) => {
+      const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+      const binary = window.atob(base64);
+      const bytes = new Uint8Array(binary.length);
+      for (let i2 = 0; i2 < binary.length; i2++) {
+        bytes[i2] = binary.charCodeAt(i2);
+      }
+      const decoder = new TextDecoder();
+      return decoder.decode(bytes);
+    }
+  };
+  getEnv(key) {
+    if (typeof import.meta !== "undefined" && __vite_import_meta_env__ && __vite_import_meta_env__[key]) {
+      return __vite_import_meta_env__[key];
+    }
+    const globalRef = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof self !== "undefined" ? self : {};
+    const anyGlobal = globalRef;
+    try {
+      if (typeof process !== "undefined" && process.env && process.env[key]) {
+        return process.env[key];
+      }
+    } catch (e2) {
+    }
+    if (anyGlobal.__MODJULES__ && anyGlobal.__MODJULES__[key]) {
+      return anyGlobal.__MODJULES__[key];
+    }
+    return void 0;
+  }
+}
+const defaultPlatform = new BrowserPlatform();
+const defaultStorageFactory = {
+  activity: (sessionId) => new BrowserStorage(sessionId),
+  session: () => new MemorySessionStorage()
+  // Use Memory for now, upgrade to IndexedDB later
+};
+function connect(options = {}) {
+  return new JulesClientImpl(options, defaultStorageFactory, defaultPlatform);
+}
+const jules = connect();
+export {
+  A as AutomatedSessionFailedError,
+  I as InvalidStateError,
+  d as JulesApiError,
+  e as JulesAuthenticationError,
+  b as JulesError,
+  c as JulesNetworkError,
+  f as JulesRateLimitError,
+  h as MissingApiKeyError,
+  i as SourceNotFoundError,
+  j as SyncInProgressError,
+  connect,
+  jules
+};
+//# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.mjs","sources":["../src/storage/browser.ts","../src/platform/browser.ts","../src/browser.ts"],"sourcesContent":["import { openDB, IDBPDatabase } from 'idb';\nimport { Activity } from '../types.js';\nimport { ActivityStorage } from './types.js';\n\nconst DB_NAME = 'jules-activities';\nconst STORE_NAME = 'activities';\n\n/**\n * Browser implementation of ActivityStorage using IndexedDB.\n * Allows for persistent storage of activities in the browser.\n */\nexport class BrowserStorage implements ActivityStorage {\n  private sessionId: string;\n  private dbPromise: Promise<IDBPDatabase<unknown>> | null = null;\n\n  constructor(sessionId: string) {\n    this.sessionId = sessionId;\n  }\n\n  private getDb(): Promise<IDBPDatabase<unknown>> {\n    if (!this.dbPromise) {\n      // We use version 2 here as well to match BrowserPlatform and avoid conflicts.\n      // We don't necessarily need to know about 'artifacts' store here, but we must use the same version.\n      this.dbPromise = openDB(DB_NAME, 2, {\n        upgrade(db, oldVersion, newVersion, transaction) {\n          if (oldVersion < 1) {\n            if (!db.objectStoreNames.contains(STORE_NAME)) {\n              const store = db.createObjectStore(STORE_NAME, {\n                keyPath: 'id',\n              });\n              // Index to efficiently find the latest activity for a session\n              store.createIndex('sessionTimestamp', [\n                'sessionId',\n                'createTime',\n              ]);\n            }\n          }\n          // Ensure artifacts store exists if we are upgrading to v2 or from scratch\n          // This might duplicate logic in BrowserPlatform, but it's safer if both can upgrade.\n          if (!db.objectStoreNames.contains('artifacts')) {\n            const store = db.createObjectStore('artifacts', {\n              keyPath: 'filepath',\n            });\n            store.createIndex('activityId', 'activityId');\n          }\n        },\n      });\n    }\n    return this.dbPromise;\n  }\n\n  /**\n   * Initializes the storage.\n   *\n   * **Side Effects:**\n   * - Opens an IndexedDB connection.\n   * - Upgrades the database schema to v2 if necessary (creating object stores).\n   */\n  async init(): Promise<void> {\n    // openDB handles initialization, so just call it to ensure DB is ready.\n    await this.getDb();\n  }\n\n  /**\n   * Closes the storage connection.\n   */\n  async close(): Promise<void> {\n    if (this.dbPromise) {\n      const db = await this.dbPromise;\n      db.close();\n      this.dbPromise = null;\n    }\n  }\n\n  /**\n   * Appends an activity to IndexedDB.\n   *\n   * **Side Effects:**\n   * - Adds a `sessionId` field to the activity for indexing.\n   * - Writes the modified activity to the `activities` object store.\n   */\n  async append(activity: Activity): Promise<void> {\n    const db = await this.getDb();\n    const tx = db.transaction(STORE_NAME, 'readwrite');\n    const store = tx.objectStore(STORE_NAME);\n    // Add sessionId to the object for indexing\n    const storableActivity = { ...activity, sessionId: this.sessionId };\n    await store.put(storableActivity);\n    await tx.done;\n  }\n\n  /**\n   * Retrieves an activity by ID.\n   */\n  async get(activityId: string): Promise<Activity | undefined> {\n    const db = await this.getDb();\n    const activity = await db.get(STORE_NAME, activityId);\n    // Strip sessionId before returning\n    if (activity) {\n      delete (activity as any).sessionId;\n    }\n    return activity as Activity | undefined;\n  }\n\n  /**\n   * Retrieves the latest activity for the current session.\n   *\n   * **Logic:**\n   * - Uses the `sessionTimestamp` index to query efficiently.\n   * - Opens a cursor in 'prev' direction to find the last entry first.\n   */\n  async latest(): Promise<Activity | undefined> {\n    const db = await this.getDb();\n    const tx = db.transaction(STORE_NAME, 'readonly');\n    const store = tx.objectStore(STORE_NAME);\n    const index = store.index('sessionTimestamp');\n\n    // Create a key range for just this session\n    const range = IDBKeyRange.bound(\n      [this.sessionId, ''],\n      [this.sessionId, new Date(8640000000000000).toISOString()],\n    );\n\n    const cursor = await index.openCursor(range, 'prev');\n    if (!cursor) {\n      return undefined;\n    }\n    const activity = cursor.value;\n    // Strip sessionId before returning\n    if (activity) {\n      delete (activity as any).sessionId;\n    }\n    return activity as Activity | undefined;\n  }\n\n  /**\n   * Yields all activities for the current session.\n   */\n  async *scan(): AsyncIterable<Activity> {\n    const db = await this.getDb();\n    const tx = db.transaction(STORE_NAME, 'readonly');\n    const store = tx.objectStore(STORE_NAME);\n    const index = store.index('sessionTimestamp');\n\n    const range = IDBKeyRange.bound(\n      [this.sessionId, ''],\n      [this.sessionId, new Date(8640000000000000).toISOString()],\n    );\n\n    let cursor = await index.openCursor(range, 'next');\n\n    while (cursor) {\n      const activity = cursor.value;\n      if (activity) {\n        delete (activity as any).sessionId;\n      }\n      yield activity as Activity;\n      cursor = await cursor.continue();\n    }\n  }\n}\n","import { openDB, IDBPDatabase } from 'idb';\nimport { Platform, PlatformResponse } from './types.js';\n\nconst DB_NAME = 'jules-activities';\nconst ARTIFACTS_STORE_NAME = 'artifacts';\nconst ACTIVITIES_STORE_NAME = 'activities';\n\n/**\n * Browser implementation of the Platform interface.\n * Uses IndexedDB for file storage.\n */\nexport class BrowserPlatform implements Platform {\n  private dbPromise: Promise<IDBPDatabase<unknown>> | null = null;\n\n  private getDb(): Promise<IDBPDatabase<unknown>> {\n    if (!this.dbPromise) {\n      this.dbPromise = openDB(DB_NAME, 2, {\n        upgrade(db, oldVersion, newVersion, transaction) {\n          // Ensure activities store exists (copied from BrowserStorage to avoid race conditions)\n          if (!db.objectStoreNames.contains(ACTIVITIES_STORE_NAME)) {\n            const store = db.createObjectStore(ACTIVITIES_STORE_NAME, {\n              keyPath: 'id',\n            });\n            store.createIndex('sessionTimestamp', ['sessionId', 'createTime']);\n          }\n          // Ensure artifacts store exists\n          if (!db.objectStoreNames.contains(ARTIFACTS_STORE_NAME)) {\n            const store = db.createObjectStore(ARTIFACTS_STORE_NAME, {\n              keyPath: 'filepath',\n            });\n            store.createIndex('activityId', 'activityId');\n          }\n        },\n      });\n    }\n    return this.dbPromise;\n  }\n\n  /**\n   * Saves a file to IndexedDB.\n   *\n   * **Data Transformation:**\n   * - Decodes base64 data into a `Blob`.\n   *\n   * **Side Effects:**\n   * - Stores the blob in the `artifacts` object store.\n   * - Associates the file with the `activityId` (if provided).\n   *\n   * @throws {Error} If the encoding is not 'base64'.\n   */\n  async saveFile(\n    filepath: string,\n    data: string,\n    encoding: 'base64',\n    activityId?: string,\n  ): Promise<void> {\n    if (encoding !== 'base64') {\n      throw new Error(`Unsupported encoding for browser saveFile: ${encoding}`);\n    }\n    const db = await this.getDb();\n    const blob = this.base64ToBlob(data);\n\n    await db.put(ARTIFACTS_STORE_NAME, {\n      filepath,\n      blob,\n      activityId,\n      createdAt: new Date().toISOString(),\n    });\n  }\n\n  async sleep(ms: number): Promise<void> {\n    await new Promise((resolve) => setTimeout(resolve, ms));\n  }\n\n  createDataUrl(data: string, mimeType: string): string {\n    return `data:${mimeType};base64,${data}`;\n  }\n\n  private base64ToBlob(data: string, mimeType?: string): Blob {\n    const byteCharacters = atob(data);\n    const byteNumbers = new Array(byteCharacters.length);\n    for (let i = 0; i < byteCharacters.length; i++) {\n      byteNumbers[i] = byteCharacters.charCodeAt(i);\n    }\n    const byteArray = new Uint8Array(byteNumbers);\n    return new Blob([byteArray], mimeType ? { type: mimeType } : undefined);\n  }\n\n  async fetch(input: string, init?: any): Promise<PlatformResponse> {\n    const res = await window.fetch(input, init);\n    return {\n      ok: res.ok,\n      status: res.status,\n      json: () => res.json(),\n      text: () => res.text(),\n    };\n  }\n\n  crypto = {\n    randomUUID: () => self.crypto.randomUUID(),\n\n    async sign(text: string, secret: string): Promise<string> {\n      const enc = new TextEncoder();\n      const key = await window.crypto.subtle.importKey(\n        'raw',\n        enc.encode(secret),\n        { name: 'HMAC', hash: 'SHA-256' },\n        false,\n        ['sign'],\n      );\n      const signature = await window.crypto.subtle.sign(\n        'HMAC',\n        key,\n        enc.encode(text),\n      );\n      return this.arrayBufferToBase64Url(signature);\n    },\n\n    async verify(\n      text: string,\n      signature: string,\n      secret: string,\n    ): Promise<boolean> {\n      const expected = await this.sign(text, secret);\n      return expected === signature;\n    },\n\n    // Helper for Base64URL encoding in browser\n    arrayBufferToBase64Url(buffer: ArrayBuffer): string {\n      const bytes = new Uint8Array(buffer);\n      let binary = '';\n      for (let i = 0; i < bytes.byteLength; i++) {\n        binary += String.fromCharCode(bytes[i]);\n      }\n      return window\n        .btoa(binary)\n        .replace(/\\+/g, '-')\n        .replace(/\\//g, '_')\n        .replace(/=+$/, '');\n    },\n  };\n\n  encoding = {\n    base64Encode: (text: string): string => {\n      // Use TextEncoder for proper UTF-8 handling before Base64\n      const encoder = new TextEncoder();\n      const bytes = encoder.encode(text);\n      let binary = '';\n      for (let i = 0; i < bytes.length; i++) {\n        binary += String.fromCharCode(bytes[i]);\n      }\n      return window\n        .btoa(binary)\n        .replace(/\\+/g, '-')\n        .replace(/\\//g, '_')\n        .replace(/=+$/, '');\n    },\n\n    base64Decode: (text: string): string => {\n      const base64 = text.replace(/-/g, '+').replace(/_/g, '/');\n      // Standard atob handles the Base64 decode, then we must interpret the bytes as UTF-8\n      const binary = window.atob(base64);\n      const bytes = new Uint8Array(binary.length);\n      for (let i = 0; i < binary.length; i++) {\n        bytes[i] = binary.charCodeAt(i);\n      }\n      const decoder = new TextDecoder();\n      return decoder.decode(bytes);\n    },\n  };\n\n  getEnv(key: string): string | undefined {\n    // 1. Vite / Modern ESM Support\n    if (\n      typeof import.meta !== 'undefined' &&\n      (import.meta as any).env &&\n      (import.meta as any).env[key]\n    ) {\n      return (import.meta as any).env[key];\n    }\n\n    // 2. Safe Global Fallbacks (window, self, globalThis)\n    const globalRef =\n      typeof globalThis !== 'undefined'\n        ? globalThis\n        : typeof window !== 'undefined'\n          ? window\n          : typeof self !== 'undefined'\n            ? self\n            : {};\n    const anyGlobal = globalRef as any;\n\n    // 3. Legacy process.env check (Safe)\n    // We strictly check for existence to avoid ReferenceError if 'process' is missing.\n    try {\n      if (typeof process !== 'undefined' && process.env && process.env[key]) {\n        return process.env[key];\n      }\n    } catch (e) {\n      // Ignore ReferenceError if process is not defined\n    }\n\n    // 4. Manual Injection Fallback\n    if (anyGlobal.__MODJULES__ && anyGlobal.__MODJULES__[key]) {\n      return anyGlobal.__MODJULES__[key];\n    }\n\n    return undefined;\n  }\n}\n","// src/browser.ts\nimport { JulesClientImpl } from './client.js';\nimport { BrowserStorage } from './storage/browser.js';\nimport { MemorySessionStorage } from './storage/memory.js';\nimport { BrowserPlatform } from './platform/browser.js';\nimport { JulesClient, JulesOptions, StorageFactory } from './types.js';\n\nconst defaultPlatform = new BrowserPlatform();\nconst defaultStorageFactory: StorageFactory = {\n  activity: (sessionId: string) => new BrowserStorage(sessionId),\n  session: () => new MemorySessionStorage(), // Use Memory for now, upgrade to IndexedDB later\n};\n\n/**\n * Connects to the Jules service with the provided configuration.\n * Acts as a factory method for creating a new client instance.\n *\n * @param options Configuration options for the client.\n * @returns A new JulesClient instance.\n */\nexport function connect(options: JulesOptions = {}): JulesClient {\n  return new JulesClientImpl(options, defaultStorageFactory, defaultPlatform);\n}\n\n/**\n * The main entry point for the Jules SDK for browser environments.\n * This is a pre-initialized client that can be used immediately with default settings.\n *\n * @example\n * import { jules } from 'modjules/browser';\n * const session = await jules.session({ ... });\n */\nexport const jules: JulesClient = connect();\n\n// Re-export all the types for convenience\nexport * from './errors.js';\nexport type {\n  Activity,\n  ActivityAgentMessaged,\n  ActivityPlanApproved,\n  ActivityPlanGenerated,\n  ActivityProgressUpdated,\n  ActivitySessionCompleted,\n  ActivitySessionFailed,\n  ActivityUserMessaged,\n  Artifact,\n  AutomatedSession,\n  BashArtifact,\n  ChangeSet,\n  GitHubRepo,\n  GitPatch,\n  JulesClient,\n  JulesOptions,\n  MediaArtifact,\n  Outcome,\n  Plan,\n  PlanStep,\n  PullRequest,\n  SessionClient,\n  SessionConfig,\n  SessionOutput,\n  SessionResource,\n  SessionState,\n  Source,\n  SourceContext,\n  SourceInput,\n  SourceManager,\n} from './types.js';\n"],"names":["DB_NAME","i","e"],"mappings":";;;AAIA,MAAMA,YAAU;AAChB,MAAM,aAAa;AAMZ,MAAM,eAA0C;AAAA,EAC7C;AAAA,EACA,YAAmD;AAAA,EAE3D,YAAY,WAAmB;AAC7B,SAAK,YAAY;AAAA,EACnB;AAAA,EAEQ,QAAwC;AAC9C,QAAI,CAAC,KAAK,WAAW;AAGnB,WAAK,YAAY,OAAOA,WAAS,GAAG;AAAA,QAClC,QAAQ,IAAI,YAAY,YAAY,aAAa;AAC/C,cAAI,aAAa,GAAG;AAClB,gBAAI,CAAC,GAAG,iBAAiB,SAAS,UAAU,GAAG;AAC7C,oBAAM,QAAQ,GAAG,kBAAkB,YAAY;AAAA,gBAC7C,SAAS;AAAA,cAAA,CACV;AAED,oBAAM,YAAY,oBAAoB;AAAA,gBACpC;AAAA,gBACA;AAAA,cAAA,CACD;AAAA,YACH;AAAA,UACF;AAGA,cAAI,CAAC,GAAG,iBAAiB,SAAS,WAAW,GAAG;AAC9C,kBAAM,QAAQ,GAAG,kBAAkB,aAAa;AAAA,cAC9C,SAAS;AAAA,YAAA,CACV;AACD,kBAAM,YAAY,cAAc,YAAY;AAAA,UAC9C;AAAA,QACF;AAAA,MAAA,CACD;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,OAAsB;AAE1B,UAAM,KAAK,MAAA;AAAA,EACb;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAAuB;AAC3B,QAAI,KAAK,WAAW;AAClB,YAAM,KAAK,MAAM,KAAK;AACtB,SAAG,MAAA;AACH,WAAK,YAAY;AAAA,IACnB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,OAAO,UAAmC;AAC9C,UAAM,KAAK,MAAM,KAAK,MAAA;AACtB,UAAM,KAAK,GAAG,YAAY,YAAY,WAAW;AACjD,UAAM,QAAQ,GAAG,YAAY,UAAU;AAEvC,UAAM,mBAAmB,EAAE,GAAG,UAAU,WAAW,KAAK,UAAA;AACxD,UAAM,MAAM,IAAI,gBAAgB;AAChC,UAAM,GAAG;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,IAAI,YAAmD;AAC3D,UAAM,KAAK,MAAM,KAAK,MAAA;AACtB,UAAM,WAAW,MAAM,GAAG,IAAI,YAAY,UAAU;AAEpD,QAAI,UAAU;AACZ,aAAQ,SAAiB;AAAA,IAC3B;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,SAAwC;AAC5C,UAAM,KAAK,MAAM,KAAK,MAAA;AACtB,UAAM,KAAK,GAAG,YAAY,YAAY,UAAU;AAChD,UAAM,QAAQ,GAAG,YAAY,UAAU;AACvC,UAAM,QAAQ,MAAM,MAAM,kBAAkB;AAG5C,UAAM,QAAQ,YAAY;AAAA,MACxB,CAAC,KAAK,WAAW,EAAE;AAAA,MACnB,CAAC,KAAK,YAAW,oBAAI,KAAK,MAAgB,GAAE,aAAa;AAAA,IAAA;AAG3D,UAAM,SAAS,MAAM,MAAM,WAAW,OAAO,MAAM;AACnD,QAAI,CAAC,QAAQ;AACX,aAAO;AAAA,IACT;AACA,UAAM,WAAW,OAAO;AAExB,QAAI,UAAU;AACZ,aAAQ,SAAiB;AAAA,IAC3B;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,OAAgC;AACrC,UAAM,KAAK,MAAM,KAAK,MAAA;AACtB,UAAM,KAAK,GAAG,YAAY,YAAY,UAAU;AAChD,UAAM,QAAQ,GAAG,YAAY,UAAU;AACvC,UAAM,QAAQ,MAAM,MAAM,kBAAkB;AAE5C,UAAM,QAAQ,YAAY;AAAA,MACxB,CAAC,KAAK,WAAW,EAAE;AAAA,MACnB,CAAC,KAAK,YAAW,oBAAI,KAAK,MAAgB,GAAE,aAAa;AAAA,IAAA;AAG3D,QAAI,SAAS,MAAM,MAAM,WAAW,OAAO,MAAM;AAEjD,WAAO,QAAQ;AACb,YAAM,WAAW,OAAO;AACxB,UAAI,UAAU;AACZ,eAAQ,SAAiB;AAAA,MAC3B;AACA,YAAM;AACN,eAAS,MAAM,OAAO,SAAA;AAAA,IACxB;AAAA,EACF;AACF;;AC7JA,MAAM,UAAU;AAChB,MAAM,uBAAuB;AAC7B,MAAM,wBAAwB;AAMvB,MAAM,gBAAoC;AAAA,EACvC,YAAmD;AAAA,EAEnD,QAAwC;AAC9C,QAAI,CAAC,KAAK,WAAW;AACnB,WAAK,YAAY,OAAO,SAAS,GAAG;AAAA,QAClC,QAAQ,IAAI,YAAY,YAAY,aAAa;AAE/C,cAAI,CAAC,GAAG,iBAAiB,SAAS,qBAAqB,GAAG;AACxD,kBAAM,QAAQ,GAAG,kBAAkB,uBAAuB;AAAA,cACxD,SAAS;AAAA,YAAA,CACV;AACD,kBAAM,YAAY,oBAAoB,CAAC,aAAa,YAAY,CAAC;AAAA,UACnE;AAEA,cAAI,CAAC,GAAG,iBAAiB,SAAS,oBAAoB,GAAG;AACvD,kBAAM,QAAQ,GAAG,kBAAkB,sBAAsB;AAAA,cACvD,SAAS;AAAA,YAAA,CACV;AACD,kBAAM,YAAY,cAAc,YAAY;AAAA,UAC9C;AAAA,QACF;AAAA,MAAA,CACD;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,MAAM,SACJ,UACA,MACA,UACA,YACe;AACf,QAAI,aAAa,UAAU;AACzB,YAAM,IAAI,MAAM,8CAA8C,QAAQ,EAAE;AAAA,IAC1E;AACA,UAAM,KAAK,MAAM,KAAK,MAAA;AACtB,UAAM,OAAO,KAAK,aAAa,IAAI;AAEnC,UAAM,GAAG,IAAI,sBAAsB;AAAA,MACjC;AAAA,MACA;AAAA,MACA;AAAA,MACA,YAAW,oBAAI,KAAA,GAAO,YAAA;AAAA,IAAY,CACnC;AAAA,EACH;AAAA,EAEA,MAAM,MAAM,IAA2B;AACrC,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAAA,EACxD;AAAA,EAEA,cAAc,MAAc,UAA0B;AACpD,WAAO,QAAQ,QAAQ,WAAW,IAAI;AAAA,EACxC;AAAA,EAEQ,aAAa,MAAc,UAAyB;AAC1D,UAAM,iBAAiB,KAAK,IAAI;AAChC,UAAM,cAAc,IAAI,MAAM,eAAe,MAAM;AACnD,aAASC,KAAI,GAAGA,KAAI,eAAe,QAAQA,MAAK;AAC9C,kBAAYA,EAAC,IAAI,eAAe,WAAWA,EAAC;AAAA,IAC9C;AACA,UAAM,YAAY,IAAI,WAAW,WAAW;AAC5C,WAAO,IAAI,KAAK,CAAC,SAAS,GAAG,WAAW,EAAE,MAAM,SAAA,IAAa,MAAS;AAAA,EACxE;AAAA,EAEA,MAAM,MAAM,OAAe,MAAuC;AAChE,UAAM,MAAM,MAAM,OAAO,MAAM,OAAO,IAAI;AAC1C,WAAO;AAAA,MACL,IAAI,IAAI;AAAA,MACR,QAAQ,IAAI;AAAA,MACZ,MAAM,MAAM,IAAI,KAAA;AAAA,MAChB,MAAM,MAAM,IAAI,KAAA;AAAA,IAAK;AAAA,EAEzB;AAAA,EAEA,SAAS;AAAA,IACP,YAAY,MAAM,KAAK,OAAO,WAAA;AAAA,IAE9B,MAAM,KAAK,MAAc,QAAiC;AACxD,YAAM,MAAM,IAAI,YAAA;AAChB,YAAM,MAAM,MAAM,OAAO,OAAO,OAAO;AAAA,QACrC;AAAA,QACA,IAAI,OAAO,MAAM;AAAA,QACjB,EAAE,MAAM,QAAQ,MAAM,UAAA;AAAA,QACtB;AAAA,QACA,CAAC,MAAM;AAAA,MAAA;AAET,YAAM,YAAY,MAAM,OAAO,OAAO,OAAO;AAAA,QAC3C;AAAA,QACA;AAAA,QACA,IAAI,OAAO,IAAI;AAAA,MAAA;AAEjB,aAAO,KAAK,uBAAuB,SAAS;AAAA,IAC9C;AAAA,IAEA,MAAM,OACJ,MACA,WACA,QACkB;AAClB,YAAM,WAAW,MAAM,KAAK,KAAK,MAAM,MAAM;AAC7C,aAAO,aAAa;AAAA,IACtB;AAAA;AAAA,IAGA,uBAAuB,QAA6B;AAClD,YAAM,QAAQ,IAAI,WAAW,MAAM;AACnC,UAAI,SAAS;AACb,eAASA,KAAI,GAAGA,KAAI,MAAM,YAAYA,MAAK;AACzC,kBAAU,OAAO,aAAa,MAAMA,EAAC,CAAC;AAAA,MACxC;AACA,aAAO,OACJ,KAAK,MAAM,EACX,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AAAA,IACtB;AAAA,EAAA;AAAA,EAGF,WAAW;AAAA,IACT,cAAc,CAAC,SAAyB;AAEtC,YAAM,UAAU,IAAI,YAAA;AACpB,YAAM,QAAQ,QAAQ,OAAO,IAAI;AACjC,UAAI,SAAS;AACb,eAASA,KAAI,GAAGA,KAAI,MAAM,QAAQA,MAAK;AACrC,kBAAU,OAAO,aAAa,MAAMA,EAAC,CAAC;AAAA,MACxC;AACA,aAAO,OACJ,KAAK,MAAM,EACX,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AAAA,IACtB;AAAA,IAEA,cAAc,CAAC,SAAyB;AACtC,YAAM,SAAS,KAAK,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG;AAExD,YAAM,SAAS,OAAO,KAAK,MAAM;AACjC,YAAM,QAAQ,IAAI,WAAW,OAAO,MAAM;AAC1C,eAASA,KAAI,GAAGA,KAAI,OAAO,QAAQA,MAAK;AACtC,cAAMA,EAAC,IAAI,OAAO,WAAWA,EAAC;AAAA,MAChC;AACA,YAAM,UAAU,IAAI,YAAA;AACpB,aAAO,QAAQ,OAAO,KAAK;AAAA,IAC7B;AAAA,EAAA;AAAA,EAGF,OAAO,KAAiC;AAEtC,QACE,OAAO,gBAAgB,eACtB,4BACA,yBAAwB,GAAG,GAC5B;AACA,aAAQ,yBAAwB,GAAG;AAAA,IACrC;AAGA,UAAM,YACJ,OAAO,eAAe,cAClB,aACA,OAAO,WAAW,cAChB,SACA,OAAO,SAAS,cACd,OACA,CAAA;AACV,UAAM,YAAY;AAIlB,QAAI;AACF,UAAI,OAAO,YAAY,eAAe,QAAQ,OAAO,QAAQ,IAAI,GAAG,GAAG;AACrE,eAAO,QAAQ,IAAI,GAAG;AAAA,MACxB;AAAA,IACF,SAASC,IAAG;AAAA,IAEZ;AAGA,QAAI,UAAU,gBAAgB,UAAU,aAAa,GAAG,GAAG;AACzD,aAAO,UAAU,aAAa,GAAG;AAAA,IACnC;AAEA,WAAO;AAAA,EACT;AACF;AC1MA,MAAM,kBAAkB,IAAI,gBAAA;AAC5B,MAAM,wBAAwC;AAAA,EAC5C,UAAU,CAAC,cAAsB,IAAI,eAAe,SAAS;AAAA,EAC7D,SAAS,MAAM,IAAI,qBAAA;AAAA;AACrB;AASO,SAAS,QAAQ,UAAwB,IAAiB;AAC/D,SAAO,IAAI,gBAAgB,SAAS,uBAAuB,eAAe;AAC5E;AAUO,MAAM,QAAqB,QAAA;"}

package/dist/caching.d.ts

@@ -0,0 +1,16 @@
+import { CachedSession } from './storage/types.js';
+export type CacheTier = 'hot' | 'warm' | 'frozen';
+/**
+ * Determines the cache tier for a session based on its state and age.
+ *
+ * Strategy:
+ * - **Frozen (Tier 3):** > 30 days old. Immutable.
+ * - **Warm (Tier 2):** Terminal state + Verified < 24h ago. High read performance.
+ * - **Hot (Tier 1):** Active or Stale. Requires network sync.
+ */
+export declare function determineCacheTier(cached: CachedSession, now?: number): CacheTier;
+/**
+ * Helper to check if a cached session is valid to return immediately.
+ * Returns true if the session is Frozen or Warm.
+ */
+export declare function isCacheValid(cached: CachedSession | undefined, now?: number): cached is CachedSession;

package/dist/client.d.ts

@@ -1,5 +1,7 @@
-import { JulesClient, JulesOptions, SessionConfig, SourceManager, AutomatedSession, SessionClient, StorageFactory } from './types.js';
+import { JulesClient, JulesOptions, SessionConfig, SourceManager, AutomatedSession, SessionClient, SessionResource, StorageFactory, JulesQuery, JulesDomain, QueryResult, SyncOptions, SyncStats } from './types.js';
+import { SessionCursor, ListSessionsOptions } from './sessions.js';
 import { Platform } from './platform/types.js';
+import { SessionStorage } from './storage/types.js';
 /**
  * The fully resolved internal configuration for the SDK.
  * @internal
@@ -18,11 +20,17 @@ export declare class JulesClientImpl implements JulesClient {
      * Manages source connections (e.g., GitHub repositories).
      */
     sources: SourceManager;
+    readonly storage: SessionStorage;
     private apiClient;
     private config;
     private options;
     private storageFactory;
     private platform;
+    /**
+     * Lock to prevent concurrent sync operations.
+     * Using a simple boolean for in-process locking.
+     */
+    private syncInProgress;
     /**
      * Creates a new instance of the JulesClient.
      *
@@ -31,6 +39,29 @@ export declare class JulesClientImpl implements JulesClient {
      * @param defaultPlatform Platform-specific implementation.
      */
     constructor(options: JulesOptions | undefined, defaultStorageFactory: StorageFactory, defaultPlatform: Platform);
+    /**
+     * Fluent API for rich local querying across sessions and activities.
+     * This method uses the modular query engine internally.
+     */
+    select<T extends JulesDomain>(query: JulesQuery<T>): Promise<QueryResult<T>[]>;
+    /**
+     * Synchronizes local state with the server.
+     * Logic:
+     * 1. Find High-Water Mark (newest local record).
+     * 2. Stream latest sessions from API.
+     * 3. Terminate stream early if 'incremental' and High-Water Mark is hit.
+     * 4. Throttled hydration of activities if depth is 'activities'.
+     */
+    sync(options?: SyncOptions): Promise<SyncStats>;
+    private getCheckpointPath;
+    private loadCheckpoint;
+    private saveCheckpoint;
+    private clearCheckpoint;
+    private _getHighWaterMark;
+    /**
+     * Helper to resolve environment variables with support for frontend prefixes.
+     */
+    private getEnv;
     /**
      * Creates a new Jules client instance with updated configuration.
      * This is an immutable operation; the original client instance remains unchanged.
@@ -39,6 +70,27 @@ export declare class JulesClientImpl implements JulesClient {
      * @returns A new JulesClient instance with the updated configuration.
      */
     with(options: JulesOptions): JulesClient;
+    /**
+     * Connects to the Jules service with the provided configuration.
+     * Acts as a factory method for creating a new client instance.
+     *
+     * @param options Configuration options for the client.
+     * @returns A new JulesClient instance.
+     */
+    connect(options: JulesOptions): JulesClient;
+    /**
+     * Retrieves a session resource using the "Iceberg" caching strategy.
+     * * - **Tier 3 (Frozen):** > 30 days old. Returns from cache immediately.
+     * - **Tier 2 (Warm):** Terminal state + Verified < 24h ago. Returns from cache.
+     * - **Tier 1 (Hot):** Active or Stale. Fetches from network, updates cache, returns.
+     */
+    getSessionResource(id: string): Promise<SessionResource>;
+    /**
+     * Lists sessions with a fluent, pagination-friendly API.
+     * @param options Configuration for pagination (pageSize, limit, pageToken)
+     * @returns A SessionCursor that can be awaited (first page) or iterated (all pages).
+     */
+    sessions(options?: ListSessionsOptions): SessionCursor;
     all<T>(items: T[], mapper: (item: T) => SessionConfig | Promise<SessionConfig>, options?: {
         concurrency?: number;
         stopOnError?: boolean;