Add Activity.preview; improve source and key immutability

Author: KrisBraun

.changeset/itchy-lies-beam.md

@@ -0,0 +1,12 @@
+---
+"@plotday/tool-outlook-calendar": minor
+"@plotday/tool-google-calendar": minor
+"@plotday/tool-linear": minor
+"@plotday/tool-asana": minor
+"@plotday/tool-gmail": minor
+"@plotday/tool-slack": minor
+"@plotday/tool-jira": minor
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: Improve immutability of Activity.source and Note.key by using IDs rather than URLs

.changeset/public-llamas-pull.md

@@ -0,0 +1,12 @@
+---
+"@plotday/tool-outlook-calendar": patch
+"@plotday/tool-google-calendar": patch
+"@plotday/tool-linear": patch
+"@plotday/tool-asana": patch
+"@plotday/tool-gmail": patch
+"@plotday/tool-slack": patch
+"@plotday/tool-jira": patch
+"@plotday/twister": patch
+---
+
+Added: Provide an activity preview

AGENTS.md

@@ -33,7 +33,7 @@ All type definitions are in `twister/src/` with full JSDoc:
 ## Common Pitfalls
 
 1. **❌ Using instance variables for state** - Use `this.set()`/`this.get()` instead (state doesn't persist between executions)
-2. **❌ Long-running operations without batching** - Break into chunks with `runTask()` (execution time limits)
+2. **❌ Long-running operations without batching** - Break into chunks with `runTask()` (request limits: ~1000 per execution)
 3. **❌ Forgetting to clean up** - Delete callbacks and stored state when done
 4. **❌ Not handling missing auth** - Always check for stored tokens before operations
 5. **❌ Passing functions to `this.callback()`** - See `tools/AGENTS.md` for critical callback serialization pattern

tools/AGENTS.md

@@ -158,6 +158,103 @@ await this.tools.callbacks.run(token, ...args);
 - RPC stubs: Function references across worker boundaries
 - Circular references: Objects referencing themselves
 
+## Critical: Callback Backward Compatibility
+
+**IMPORTANT:** All callbacks automatically upgrade to new twist/tool versions when a new version is deployed. You **MUST** maintain backward compatibility in ALL callback methods to prevent breaking existing callbacks.
+
+### Backward Compatibility Rules
+
+- ❌ **DON'T** change function signatures (remove/reorder parameters, change types)
+- ❌ **DON'T** change callback signatures passed to `createFromParent()`
+- ✅ **DO** add optional parameters at the end
+- ✅ **DO** use version guards for behavioral changes
+- ✅ **DO** handle both old and new data formats
+
+### What Callbacks Auto-Upgrade?
+
+All callbacks automatically upgrade to the new twist version:
+- **Webhook handlers** (onWebhook, onCalendarWebhook, etc.)
+- **Batch processing callbacks** (syncBatch, processBatch, etc.)
+- **Scheduled callbacks** (renewWatch, cleanupExpired, etc.)
+- **Tool→Twist callbacks** (onEvent, handleActivity, etc.)
+- **Internal tool callbacks** (any method called via `this.callback()`)
+
+### Examples: Good and Bad Practices
+
+```typescript
+// v1.0 - Original
+async syncBatch(batchNumber: number, authToken: string, calendarId: string) {
+  // Sync logic
+}
+
+// v1.1 - ✅ GOOD: Optional parameter added at the end
+async syncBatch(
+  batchNumber: number,
+  authToken: string,
+  calendarId: string,
+  initialSync?: boolean  // New optional parameter
+) {
+  const isInitial = initialSync ?? true; // Safe default
+  // Sync logic with initialSync support
+}
+
+// v2.0 - ❌ BAD: Breaking change
+async syncBatch(options: SyncOptions) {  // Completely changed signature!
+  // Existing batch callbacks will fail when they pass (number, string, string)
+}
+
+// v2.0 - ✅ GOOD: Handle both old and new signatures
+async syncBatch(
+  batchNumberOrOptions: number | SyncOptions,
+  authToken?: string,
+  calendarId?: string,
+  initialSync?: boolean
+) {
+  let options: SyncOptions;
+
+  if (typeof batchNumberOrOptions === "number") {
+    // Old version - reconstruct options from individual parameters
+    options = {
+      batchNumber: batchNumberOrOptions,
+      authToken: authToken!,
+      calendarId: calendarId!,
+      initialSync,
+    };
+  } else {
+    // New version - use options object directly
+    options = batchNumberOrOptions;
+  }
+
+  // Sync logic using options
+}
+```
+
+### Handling Breaking Changes
+
+If you **must** make a breaking change, implement migration logic in the `upgrade()` hook:
+
+```typescript
+async upgrade(oldVersion: string, newVersion: string) {
+  if (oldVersion === "1.0" && newVersion === "2.0") {
+    // Get all in-progress syncs and recreate callbacks with new signature
+    const syncs = await this.get<SyncState[]>("active_syncs");
+
+    for (const sync of syncs) {
+      // Stop old sync
+      await this.stopSync(sync.authToken, sync.calendarId);
+
+      // Restart with new callback signature
+      await this.startSync({
+        authToken: sync.authToken,
+        calendarId: sync.calendarId,
+      }, this.onEvent);
+    }
+  }
+}
+```
+
+**Note:** Users will need to uninstall and reinstall the twist/tool if breaking changes aren't properly migrated.
+
 ## Tool Development Checklist
 
 Building a tool? Follow this checklist:
@@ -169,7 +266,9 @@ Building a tool? Follow this checklist:
 - [ ] **Store callback tokens**, don't pass them as arguments
 - [ ] **Pass only serializable values** to `this.callback()`
 - [ ] Retrieve tokens with `this.get()` and execute with `callbacks.run()`
-- [ ] Use batch processing for long operations (see `../twister/cli/templates/AGENTS.template.md`)
+- [ ] Use batch processing for long operations - break loops into chunks to stay under ~1000 requests per execution
+- [ ] Size batches appropriately - calculate requests per item to determine safe batch size
+- [ ] Use `this.runTask()` to create new executions with fresh request limits
 - [ ] Clean up stored state and callbacks in lifecycle methods
 
 ## Common Tool Pitfalls
@@ -179,6 +278,7 @@ Building a tool? Follow this checklist:
 3. **❌ Not validating callback token exists** - Always check before `callbacks.run()`
 4. **❌ Forgetting to store the callback token** - Store it immediately after creating
 5. **❌ Passing undefined instead of null** - Use `null` for optional values
+6. **❌ Not breaking loops into batches** - Each execution has ~1000 request limit; use `runTask()` for fresh limits
 
 ---