@plotday/twister 0.31.2 → 0.32.0

package/bin/templates/AGENTS.template.md

@@ -11,9 +11,11 @@ Plot Twists are TypeScript classes that extend the `Twist` base class. Twists in
 **Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
 
 - **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
-- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
-- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`
-- **Break long operations**: Split large operations into smaller batches that can be processed independently
+- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)
+- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)
+- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit
+- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count
+- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit
 - **Store intermediate state**: Use the Store tool to persist state between batches
 - **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
 
@@ -455,14 +457,16 @@ async onCalendarSelected(
 
 ## Batch Processing Pattern
 
-**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.
+**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.
 
 ### Key Principles
 
-1. **Store state between batches**: Use the Store tool to persist progress
-2. **Queue next batch**: Use the Run tool to schedule the next chunk
-3. **Clean up when done**: Delete stored state after completion
-4. **Handle failures**: Store enough state to resume if a batch fails
+1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.
+2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests
+3. **Store state between batches**: Use the Store tool to persist progress
+4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)
+5. **Clean up when done**: Delete stored state after completion
+6. **Handle failures**: Store enough state to resume if a batch fails
 
 ### Example Implementation
 
@@ -473,10 +477,12 @@ async startSync(resourceId: string): Promise<void> {
     nextPageToken: null,
     batchNumber: 1,
     itemsProcessed: 0,
+    initialSync: true,  // Track whether this is the first sync
   });
 
   // Queue first batch using runTask method
   const callback = await this.callback(this.syncBatch, resourceId);
+  // runTask creates NEW execution with fresh ~1000 request limit
   await this.runTask(callback);
 }
 
@@ -484,11 +490,13 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
   // Load state from Store (set by previous execution)
   const state = await this.get(`sync_state_${resourceId}`);
 
-  // Process one batch (keep under time limit)
+  // Process one batch (size to stay under ~1000 request limit)
   const result = await this.fetchBatch(state.nextPageToken);
 
   // Process results using source/key pattern (automatic upserts, no manual tracking)
+  // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit
   for (const item of result.items) {
+    // Each createActivity may make ~5-10 requests depending on notes/links
     await this.tools.plot.createActivity({
       source: item.url, // Use item's canonical URL for automatic deduplication
       type: ActivityType.Note,
@@ -498,6 +506,8 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
         key: "description", // Use key for upsertable notes
         content: item.description,
       }],
+      unread: !state.initialSync, // false for initial sync, true for incremental
+      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only
     });
   }
 
@@ -507,9 +517,10 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
       nextPageToken: result.nextPageToken,
       batchNumber: state.batchNumber + 1,
       itemsProcessed: state.itemsProcessed + result.items.length,
+      initialSync: state.initialSync, // Preserve initialSync flag across batches
     });
 
-    // Queue next batch (runs in new execution context)
+    // Queue next batch - creates NEW execution with fresh request limit
     const nextCallback = await this.callback(this.syncBatch, resourceId);
     await this.runTask(nextCallback);
   } else {
@@ -530,6 +541,35 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
 }
 ```
 
+## Activity Sync Best Practices
+
+When syncing activities from external systems, follow these patterns for optimal user experience:
+
+### The `initialSync` Flag
+
+All sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):
+
+| Field | Initial Sync | Incremental Sync | Reason |
+|-------|--------------|------------------|---------|
+| `unread` | `false` | `true` | Avoid notification overload from historical items |
+| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |
+
+**Example:**
+```typescript
+const activity: NewActivity = {
+  type: ActivityType.Event,
+  source: event.url,
+  title: event.title,
+  unread: !initialSync,                      // false for initial, true for incremental
+  ...(initialSync ? { archived: false } : {}),  // unarchive on initial only
+};
+```
+
+**Why this matters:**
+- **Initial sync**: Activities are unarchived and marked as read, preventing spam from bulk historical imports
+- **Incremental sync**: New activities appear as unread, and archived state is preserved (respects user's archiving decisions)
+- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)
+
 ## Error Handling
 
 Always handle errors gracefully and communicate them to users:
@@ -561,11 +601,12 @@ try {
 - **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
 - **Add Notes to existing Activities** - For source/key pattern, reference activities by source. For UUID pattern, look up stored mappings before creating new Activities. Think thread replies, not new threads.
 - Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
-- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.
+- **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).
 - **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.
 - **Store auth tokens** - Don't re-request authentication unnecessarily.
 - **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.
 - **Handle missing auth gracefully** - Check for stored auth before operations.
+- **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.
 
 ## Testing
 

package/bin/utils/token.js

@@ -33,43 +33,71 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getGlobalTokenPath = getGlobalTokenPath;
+exports.getNamespacedTokenPath = getNamespacedTokenPath;
+exports.resolveToken = resolveToken;
 exports.getToken = getToken;
 const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const url_normalize_js_1 = require("./url-normalize.js");
 /**
- * Get the path to the global token file.
- *
- * @returns The path to the global token file
+ * Get the namespaced token path for a specific API URL.
  */
-function getGlobalTokenPath() {
-    const homeDir = os.homedir();
-    if (process.platform === "win32") {
-        // Windows: Use APPDATA
-        const appData = process.env.APPDATA || path.join(homeDir, "AppData", "Roaming");
-        return path.join(appData, "plot", "token");
-    }
-    else {
-        // Unix-like: Use ~/.config/plot/token
-        return path.join(homeDir, ".config", "plot", "token");
-    }
+function getNamespacedTokenPath(apiUrl) {
+    const namespace = (0, url_normalize_js_1.normalizeApiUrl)(apiUrl);
+    const configDir = process.platform === "win32"
+        ? process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming")
+        : path.join(os.homedir(), ".config");
+    return path.join(configDir, "plot", "credentials", namespace, "token");
 }
 /**
- * Read the authentication token from the global token file.
+ * Resolve token using the complete resolution chain:
+ * 1. --deploy-token CLI flag
+ * 2. PLOT_DEPLOY_TOKEN env var
+ * 3. .env file DEPLOY_TOKEN
+ * 4. Namespaced token file
  *
- * @returns The token string if found, null otherwise
+ * Returns undefined if no token found (caller handles prompting).
  */
-async function getToken() {
-    const globalTokenPath = getGlobalTokenPath();
-    if (fs.existsSync(globalTokenPath)) {
+function resolveToken(options) {
+    // Step 1: CLI flag
+    if (options.deployToken) {
+        return options.deployToken;
+    }
+    // Step 2: PLOT_DEPLOY_TOKEN env var
+    if (options.envToken) {
+        return options.envToken;
+    }
+    // Step 3: .env file DEPLOY_TOKEN
+    if (options.dotEnvToken) {
+        return options.dotEnvToken;
+    }
+    // Step 4: Namespaced token file
+    if (options.apiUrl) {
         try {
-            return fs.readFileSync(globalTokenPath, "utf-8").trim();
+            const namespacedPath = getNamespacedTokenPath(options.apiUrl);
+            if (fs.existsSync(namespacedPath)) {
+                const token = fs.readFileSync(namespacedPath, "utf-8").trim();
+                if (token) {
+                    return token;
+                }
+            }
         }
         catch (error) {
-            console.warn(`Warning: Failed to read global token file: ${globalTokenPath}`);
+            // Invalid API URL or file read error
+            console.error(`Warning: Could not read namespaced token: ${error}`);
         }
     }
-    return null;
+    // Step 5: Prompt (handled by caller)
+    return undefined;
+}
+/**
+ * Legacy getToken() function updated to use resolveToken().
+ */
+async function getToken() {
+    const token = resolveToken({
+        apiUrl: process.env.PLOT_API_URL || "https://api.plot.day",
+    });
+    return token || null;
 }
 //# sourceMappingURL=token.js.map

package/bin/utils/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../cli/utils/token.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASA,gDAUC;AAOD,4BAYC;AAtCD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAE7B;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,uBAAuB;QACvB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,sCAAsC;QACtC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,QAAQ;IAC5B,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;IAC7C,IAAI,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC1D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CACV,8CAA8C,eAAe,EAAE,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../cli/utils/token.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,wDAQC;AA4BD,oCAoCC;AAKD,4BAKC;AA1FD,uCAAyB;AACzB,2CAA6B;AAC7B,uCAAyB;AACzB,yDAAqD;AAErD;;GAEG;AACH,SAAgB,sBAAsB,CAAC,MAAc;IACnD,MAAM,SAAS,GAAG,IAAA,kCAAe,EAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,SAAS,GACb,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC1B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC;QACtE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAEzC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAmBD;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAC1B,OAA+B;IAE/B,mBAAmB;IACnB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,WAAW,CAAC;IAC7B,CAAC;IAED,oCAAoC;IACpC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC,QAAQ,CAAC;IAC1B,CAAC;IAED,iCAAiC;IACjC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,WAAW,CAAC;IAC7B,CAAC;IAED,gCAAgC;IAChC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,sBAAsB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC9D,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;gBAClC,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC9D,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qCAAqC;YACrC,OAAO,CAAC,KAAK,CAAC,6CAA6C,KAAK,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,QAAQ;IAC5B,MAAM,KAAK,GAAG,YAAY,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,sBAAsB;KAC3D,CAAC,CAAC;IACH,OAAO,KAAK,IAAI,IAAI,CAAC;AACvB,CAAC"}

package/bin/utils/url-normalize.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeApiUrl = normalizeApiUrl;
+/**
+ * Normalize API URL to a filesystem-safe namespace identifier.
+ *
+ * Examples:
+ *   https://api.plot.day → api.plot.day
+ *   http://localhost:8787 → localhost-8787
+ *   https://api.plot.day/ → api.plot.day (trailing slash removed)
+ *   http://[::1]:8787 → ::1-8787 (IPv6 supported)
+ *   https://api.plot.day/v2 → api.plot.day (path ignored)
+ *
+ * @throws {Error} If URL is malformed or invalid
+ */
+function normalizeApiUrl(apiUrl) {
+    let url;
+    try {
+        url = new URL(apiUrl);
+    }
+    catch (error) {
+        throw new Error(`Invalid API URL: ${apiUrl}`);
+    }
+    // Reject non-http(s) protocols
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Invalid API URL protocol: ${url.protocol} (must be http or https)`);
+    }
+    // Extract hostname (handles IPv6 by removing brackets)
+    let hostname = url.hostname;
+    // Get port
+    const port = url.port;
+    // Omit standard ports (80 for http, 443 for https)
+    const isStandardPort = (url.protocol === "http:" && port === "80") ||
+        (url.protocol === "https:" && port === "443") ||
+        !port;
+    if (isStandardPort) {
+        return hostname;
+    }
+    // For non-standard ports, append with dash separator
+    // (works for both IPv4/IPv6 since hostname has brackets removed)
+    return `${hostname}-${port}`;
+}
+//# sourceMappingURL=url-normalize.js.map

package/bin/utils/url-normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-normalize.js","sourceRoot":"","sources":["../../cli/utils/url-normalize.ts"],"names":[],"mappings":";;AAYA,0CAmCC;AA/CD;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAAC,MAAc;IAC5C,IAAI,GAAQ,CAAC;IAEb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,+BAA+B;IAC/B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,6BAA6B,GAAG,CAAC,QAAQ,0BAA0B,CACpE,CAAC;IACJ,CAAC;IAED,uDAAuD;IACvD,IAAI,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAE5B,WAAW;IACX,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAEtB,mDAAmD;IACnD,MAAM,cAAc,GAClB,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,IAAI,KAAK,IAAI,CAAC;QAC3C,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,KAAK,KAAK,CAAC;QAC7C,CAAC,IAAI,CAAC;IAER,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,qDAAqD;IACrD,iEAAiE;IACjE,OAAO,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC;AAC/B,CAAC"}

package/cli/templates/AGENTS.template.md

@@ -11,9 +11,11 @@ Plot Twists are TypeScript classes that extend the `Twist` base class. Twists in
 **Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
 
 - **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
-- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
-- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`
-- **Break long operations**: Split large operations into smaller batches that can be processed independently
+- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)
+- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)
+- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit
+- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count
+- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit
 - **Store intermediate state**: Use the Store tool to persist state between batches
 - **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
 
@@ -455,14 +457,16 @@ async onCalendarSelected(
 
 ## Batch Processing Pattern
 
-**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.
+**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.
 
 ### Key Principles
 
-1. **Store state between batches**: Use the Store tool to persist progress
-2. **Queue next batch**: Use the Run tool to schedule the next chunk
-3. **Clean up when done**: Delete stored state after completion
-4. **Handle failures**: Store enough state to resume if a batch fails
+1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.
+2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests
+3. **Store state between batches**: Use the Store tool to persist progress
+4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)
+5. **Clean up when done**: Delete stored state after completion
+6. **Handle failures**: Store enough state to resume if a batch fails
 
 ### Example Implementation
 
@@ -473,10 +477,12 @@ async startSync(resourceId: string): Promise<void> {
     nextPageToken: null,
     batchNumber: 1,
     itemsProcessed: 0,
+    initialSync: true,  // Track whether this is the first sync
   });
 
   // Queue first batch using runTask method
   const callback = await this.callback(this.syncBatch, resourceId);
+  // runTask creates NEW execution with fresh ~1000 request limit
   await this.runTask(callback);
 }
 
@@ -484,11 +490,13 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
   // Load state from Store (set by previous execution)
   const state = await this.get(`sync_state_${resourceId}`);
 
-  // Process one batch (keep under time limit)
+  // Process one batch (size to stay under ~1000 request limit)
   const result = await this.fetchBatch(state.nextPageToken);
 
   // Process results using source/key pattern (automatic upserts, no manual tracking)
+  // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit
   for (const item of result.items) {
+    // Each createActivity may make ~5-10 requests depending on notes/links
     await this.tools.plot.createActivity({
       source: item.url, // Use item's canonical URL for automatic deduplication
       type: ActivityType.Note,
@@ -498,6 +506,8 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
         key: "description", // Use key for upsertable notes
         content: item.description,
       }],
+      unread: !state.initialSync, // false for initial sync, true for incremental
+      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only
     });
   }
 
@@ -507,9 +517,10 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
       nextPageToken: result.nextPageToken,
       batchNumber: state.batchNumber + 1,
       itemsProcessed: state.itemsProcessed + result.items.length,
+      initialSync: state.initialSync, // Preserve initialSync flag across batches
     });
 
-    // Queue next batch (runs in new execution context)
+    // Queue next batch - creates NEW execution with fresh request limit
     const nextCallback = await this.callback(this.syncBatch, resourceId);
     await this.runTask(nextCallback);
   } else {
@@ -530,6 +541,35 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
 }
 ```
 
+## Activity Sync Best Practices
+
+When syncing activities from external systems, follow these patterns for optimal user experience:
+
+### The `initialSync` Flag
+
+All sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):
+
+| Field | Initial Sync | Incremental Sync | Reason |
+|-------|--------------|------------------|---------|
+| `unread` | `false` | `true` | Avoid notification overload from historical items |
+| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |
+
+**Example:**
+```typescript
+const activity: NewActivity = {
+  type: ActivityType.Event,
+  source: event.url,
+  title: event.title,
+  unread: !initialSync,                      // false for initial, true for incremental
+  ...(initialSync ? { archived: false } : {}),  // unarchive on initial only
+};
+```
+
+**Why this matters:**
+- **Initial sync**: Activities are unarchived and marked as read, preventing spam from bulk historical imports
+- **Incremental sync**: New activities appear as unread, and archived state is preserved (respects user's archiving decisions)
+- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)
+
 ## Error Handling
 
 Always handle errors gracefully and communicate them to users:
@@ -561,11 +601,12 @@ try {
 - **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
 - **Add Notes to existing Activities** - For source/key pattern, reference activities by source. For UUID pattern, look up stored mappings before creating new Activities. Think thread replies, not new threads.
 - Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
-- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.
+- **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).
 - **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.
 - **Store auth tokens** - Don't re-request authentication unnecessarily.
 - **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.
 - **Handle missing auth gracefully** - Check for stored auth before operations.
+- **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.
 
 ## Testing
 

package/dist/common/calendar.d.ts

@@ -34,10 +34,25 @@ export type Calendar = {
  * Used to limit sync scope and optimize performance.
  */
 export type SyncOptions = {
-    /** Earliest date to sync events from (inclusive) */
-    timeMin?: Date;
-    /** Latest date to sync events to (exclusive) */
-    timeMax?: Date;
+    /**
+     * Earliest date to sync events from (inclusive).
+     * - If undefined: defaults to 2 years in the past
+     * - If null: syncs all history from the beginning of time
+     * - If Date: syncs from the specified date
+     */
+    timeMin?: Date | null;
+    /**
+     * Latest date to sync events to (exclusive).
+     * - If undefined: no limit (syncs all future events)
+     * - If null: no limit (syncs all future events)
+     * - If Date: syncs up to but not including the specified date
+     *
+     * Use cases:
+     * - Daily digest: Set to end of today
+     * - Week view: Set to end of current week
+     * - Performance: Limit initial sync range
+     */
+    timeMax?: Date | null;
 };
 /**
  * Base interface for calendar integration tools.

package/dist/common/calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/common/calendar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,WAAW,CACT,KAAK,SAAS,YAAY,EAAE,EAC5B,SAAS,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,GAAG,EAE7D,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,KAAK,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CACP,KAAK,SAAS,YAAY,EAAE,EAC5B,SAAS,SAAS,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,GAAG,EAEzE,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,WAAW,EACf,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,KAAK,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE,CAAC"}
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/common/calendar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,WAAW,CACT,KAAK,SAAS,YAAY,EAAE,EAC5B,SAAS,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,GAAG,EAE7D,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,KAAK,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CACP,KAAK,SAAS,YAAY,EAAE,EAC5B,SAAS,SAAS,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,GAAG,EAEzE,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,WAAW,EACf,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,KAAK,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE,CAAC"}

package/dist/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "eJyNkrFuwyAQht/l5gslFTbYW9TJS1Wp3aqoojZNLBNTwVUZIr97hd1WdIKFAb7//w7pbuCdowDta1MdEbz5sKan0c0B2hs0VTxnfTHQQvfinAWEaZwHaPf3CuHLW2ihtzoEE+7IOctWip3pEtH1BVqgMOxibLddIPTn0Q7ezNGrUAiBQgqsK4mSS5Q1R8X3qFSNDRfHBaFRySRFgxTMsSAIIdLi6xgo5KrDG60c2/ACiUwlhy4v0CM7dPniupJJ8YO29l33U8EH+l+U/YXyNslTWzeTOXm97UpWOCY0S6MF2pon2kdDV+envHHeQPYTyHsU3yeeJ+soL/m0jlhEC+pVndQ/k/Mm3x8ixlY4b2j4v13WoWQTKGJshXOGZfkGZ4dciQ=="
+window.hierarchyData = "eJyNkrFuwyAQht/l5gslDTHgLerkparUblVUUYc0Voip4KoMkd+9wm4rOsHCAN//f4d0NwjeU4T2VW/3CMEene1p8GOE9gZ6m87RXCy00L147wDhPIwHaNf3CuErOGihdyZGG+/Ie8dmip3oktD5BVqgeFil2Gq5QOhPgzsEOyavQiEkCimxaTjKNUfZbFBxgUpp1FzuJwStskmqBqmYY0IQQubF1yFSLFXHN5o5tuAVEplLdl1ZYAa268rFTcOz4gfj3LvpzxUf6H9R9hcq2+Q6t3Uj2Y9gll0pCoeMZnm0QttsMu2jpasP57JxXED2Eyh7FBeZ58l5Kks+nSeW0Ip6pbP6Z/LBlvtjwtgMlw2a/9tlE2s2gRLGZrhkmKZvf4JclQ=="