npm - @plotday/twister - Versions diffs - 0.31.2 → 0.32.0 - Mend

@plotday/twister 0.31.2 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/bin/commands/deploy.js +40 -51
package/bin/commands/deploy.js.map +1 -1
package/bin/commands/generate.js +13 -19
package/bin/commands/generate.js.map +1 -1
package/bin/commands/login.js +16 -20
package/bin/commands/login.js.map +1 -1
package/bin/commands/priority-create.js +5 -2
package/bin/commands/priority-create.js.map +1 -1
package/bin/commands/priority-list.js +5 -2
package/bin/commands/priority-list.js.map +1 -1
package/bin/commands/twist-logs.js +7 -19
package/bin/commands/twist-logs.js.map +1 -1
package/bin/templates/AGENTS.template.md +52 -11
package/bin/utils/token.js +52 -24
package/bin/utils/token.js.map +1 -1
package/bin/utils/url-normalize.js +43 -0
package/bin/utils/url-normalize.js.map +1 -0
package/cli/templates/AGENTS.template.md +52 -11
package/dist/common/calendar.d.ts +19 -4
package/dist/common/calendar.d.ts.map +1 -1
package/dist/docs/assets/hierarchy.js +1 -1
package/dist/docs/assets/search.js +1 -1
package/dist/docs/classes/tool.Tool.html +18 -10
package/dist/docs/classes/tools_ai.AI.html +1 -1
package/dist/docs/classes/tools_callbacks.Callbacks.html +1 -1
package/dist/docs/classes/tools_integrations.Integrations.html +1 -1
package/dist/docs/classes/tools_network.Network.html +1 -1
package/dist/docs/classes/tools_plot.Plot.html +1 -1
package/dist/docs/classes/tools_store.Store.html +1 -1
package/dist/docs/classes/tools_tasks.Tasks.html +36 -13
package/dist/docs/classes/tools_twists.Twists.html +1 -1
package/dist/docs/documents/Building_Custom_Tools.html +10 -0
package/dist/docs/documents/Built-in_Tools.html +39 -4
package/dist/docs/documents/Core_Concepts.html +22 -1
package/dist/docs/documents/Runtime_Environment.html +32 -19
package/dist/docs/enums/plot.ActorType.html +4 -4
package/dist/docs/enums/tag.Tag.html +1 -1
package/dist/docs/hierarchy.html +1 -1
package/dist/docs/media/SYNC_STRATEGIES.md +118 -0
package/dist/docs/types/common_calendar.CalendarTool.html +23 -7
package/dist/docs/types/common_calendar.SyncOptions.html +20 -4
package/dist/docs/types/plot.Activity.html +15 -3
package/dist/docs/types/plot.ActivityOccurrence.html +7 -7
package/dist/docs/types/plot.ActivityOccurrenceUpdate.html +1 -1
package/dist/docs/types/plot.ActivityUpdate.html +10 -2
package/dist/docs/types/plot.ActivityWithNotes.html +1 -1
package/dist/docs/types/plot.Actor.html +5 -5
package/dist/docs/types/plot.ContentType.html +1 -1
package/dist/docs/types/plot.NewActivity.html +21 -2
package/dist/docs/types/plot.NewActivityOccurrence.html +5 -2
package/dist/docs/types/plot.NewActivityWithNotes.html +1 -1
package/dist/docs/types/plot.NewActor.html +1 -1
package/dist/docs/types/plot.NewContact.html +4 -4
package/dist/docs/types/plot.NewNote.html +4 -1
package/dist/docs/types/plot.Note.html +15 -4
package/dist/docs/types/plot.NoteUpdate.html +1 -1
package/dist/docs/types/plot.PickPriorityConfig.html +2 -2
package/dist/llm-docs/common/calendar.d.ts +1 -1
package/dist/llm-docs/common/calendar.d.ts.map +1 -1
package/dist/llm-docs/common/calendar.js +1 -1
package/dist/llm-docs/common/calendar.js.map +1 -1
package/dist/llm-docs/plot.d.ts +1 -1
package/dist/llm-docs/plot.d.ts.map +1 -1
package/dist/llm-docs/plot.js +1 -1
package/dist/llm-docs/plot.js.map +1 -1
package/dist/llm-docs/tag.d.ts +1 -1
package/dist/llm-docs/tag.d.ts.map +1 -1
package/dist/llm-docs/tag.js +1 -1
package/dist/llm-docs/tag.js.map +1 -1
package/dist/llm-docs/tool.d.ts +1 -1
package/dist/llm-docs/tool.d.ts.map +1 -1
package/dist/llm-docs/tool.js +1 -1
package/dist/llm-docs/tool.js.map +1 -1
package/dist/llm-docs/tools/tasks.d.ts +1 -1
package/dist/llm-docs/tools/tasks.d.ts.map +1 -1
package/dist/llm-docs/tools/tasks.js +1 -1
package/dist/llm-docs/tools/tasks.js.map +1 -1
package/dist/llm-docs/twist-guide-template.d.ts +1 -1
package/dist/llm-docs/twist-guide-template.d.ts.map +1 -1
package/dist/llm-docs/twist-guide-template.js +1 -1
package/dist/llm-docs/twist-guide-template.js.map +1 -1
package/dist/plot.d.ts +72 -6
package/dist/plot.d.ts.map +1 -1
package/dist/plot.js.map +1 -1
package/dist/tag.d.ts.map +1 -1
package/dist/tag.js +2 -0
package/dist/tag.js.map +1 -1
package/dist/tool.d.ts +15 -1
package/dist/tool.d.ts.map +1 -1
package/dist/tool.js +15 -1
package/dist/tool.js.map +1 -1
package/dist/tools/tasks.d.ts +52 -13
package/dist/tools/tasks.d.ts.map +1 -1
package/dist/tools/tasks.js +34 -10
package/dist/tools/tasks.js.map +1 -1
package/dist/twist-guide.d.ts +1 -1
package/dist/twist-guide.d.ts.map +1 -1
package/package.json +1 -1

package/dist/docs/classes/tools_tasks.Tasks.html CHANGED Viewed

@@ -1,39 +1,62 @@
 <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Tasks | Creating Plot Twists</title><link rel="icon" href="../assets/favicon.svg" type="image/svg+xml"/><meta name="description" content="Documentation for Creating Plot Twists"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="/" class="title">Creating Plot Twists</a><div id="tsd-toolbar-links"><a href="https://plot.day">Plot</a><a href="https://github.com/plotday/plot">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister">NPM</a></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="../modules/tools_tasks.html">tools/tasks</a></li><li><a href="" aria-current="page">Tasks</a></li></ul><h1>Class Tasks<code class="tsd-tag">Abstract</code></h1></div><section class="tsd-panel tsd-comment"><div class="tsd-comment tsd-typography"><p>Run background tasks and scheduled jobs.</p>
-<p>The Tasks tool enables twists and tools to queue callbacks. This is especially
-important for long-running operations and batch processing, since twists
-operate within runtime limits. Task callbacks also benefit from automatic
-retries on failure.</p>
+<p>The Tasks tool enables twists and tools to queue callbacks for execution in separate
+worker contexts. <strong>This is critical for staying under request limits</strong>: each execution
+has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and
+running a task creates a NEW execution with a fresh request limit.</p>
+<p><strong>Key distinction:</strong></p>
+<ul>
+<li><strong>Calling a callback</strong> (via <code>this.run()</code>) continues the same execution and shares the request count</li>
+<li><strong>Running a task</strong> (via <code>this.runTask()</code>) creates a NEW execution with fresh ~1000 request limit</li>
+</ul>
+<p><strong>When to use tasks:</strong></p>
+<ul>
+<li>Processing large datasets that would exceed 1000 requests</li>
+<li>Breaking loops into chunks where each chunk stays under the request limit</li>
+<li>Scheduling operations for future execution</li>
+</ul>
 <p><strong>Note:</strong> Tasks tool methods are also available directly on Twist and Tool classes
 via <code>this.runTask()</code>, <code>this.cancelTask()</code>, and <code>this.cancelAllTasks()</code>.
 This is the recommended approach for most use cases.</p>
 <p><strong>Best Practices:</strong></p>
 <ul>
-<li>Break long operations into smaller batches</li>
+<li>Size batches to stay under ~1000 requests per execution</li>
+<li>Calculate requests per item to determine safe batch size</li>
 <li>Create callbacks first using <code>this.callback()</code></li>
 <li>Store intermediate state using the Store tool</li>
 </ul>
-</div><div class="tsd-comment tsd-typography"><div class="tsd-tag-example"><h4 class="tsd-anchor-link" id="example">Example<a href="#example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript"><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">SyncTool</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Tool</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">startBatchSync</span><span class="hl-1">(</span><span class="hl-2">totalItems</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Store initial state using built-in set method</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_progress&quot;</span><span class="hl-1">, { </span><span class="hl-2">processed:</span><span class="hl-1"> </span><span class="hl-14">0</span><span class="hl-1">, </span><span class="hl-2">total:</span><span class="hl-1"> </span><span class="hl-2">totalItems</span><span class="hl-1"> });</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// Create callback and queue first batch using built-in methods</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;processBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1"> });</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">processBatch</span><span class="hl-1">(</span><span class="hl-2">args</span><span class="hl-1">: </span><span class="hl-5">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">batchNumber</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Process one batch of items</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">progress</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_progress&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// ... process items ...</span><br/><br/><span class="hl-1">    </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">processed</span><span class="hl-1"> &lt; </span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">total</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-7">// Queue next batch using built-in methods</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;processBatch&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">        </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">batchNumber</span><span class="hl-1"> + </span><span class="hl-14">1</span><br/><span class="hl-1">      });</span><br/><span class="hl-1">      </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">scheduleCleanup</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">tomorrow</span><span class="hl-1"> = </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">();</span><br/><span class="hl-1">    </span><span class="hl-2">tomorrow</span><span class="hl-1">.</span><span class="hl-6">setDate</span><span class="hl-1">(</span><span class="hl-2">tomorrow</span><span class="hl-1">.</span><span class="hl-6">getDate</span><span class="hl-1">() + </span><span class="hl-14">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;cleanupOldData&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">run</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">, { </span><span class="hl-2">runAt:</span><span class="hl-1"> </span><span class="hl-2">tomorrow</span><span class="hl-1"> });</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</div><div class="tsd-comment tsd-typography"><div class="tsd-tag-example"><h4 class="tsd-anchor-link" id="example">Example<a href="#example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript"><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">SyncTool</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Tool</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">startBatchSync</span><span class="hl-1">(</span><span class="hl-2">totalItems</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Store initial state using built-in set method</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_progress&quot;</span><span class="hl-1">, { </span><span class="hl-2">processed:</span><span class="hl-1"> </span><span class="hl-14">0</span><span class="hl-1">, </span><span class="hl-2">total:</span><span class="hl-1"> </span><span class="hl-2">totalItems</span><span class="hl-1"> });</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// Create callback and queue first batch</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;processBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1"> });</span><br/><span class="hl-1">    </span><span class="hl-7">// runTask creates NEW execution with fresh ~1000 request limit</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">processBatch</span><span class="hl-1">(</span><span class="hl-2">args</span><span class="hl-1">: </span><span class="hl-5">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">batchNumber</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Process one batch of items (sized to stay under request limit)</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">progress</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_progress&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// If each item makes ~10 requests, process ~100 items per batch</span><br/><span class="hl-1">    </span><span class="hl-7">// 100 items × 10 requests = 1000 requests (at limit)</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">batchSize</span><span class="hl-1"> = </span><span class="hl-14">100</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">items</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">fetchItems</span><span class="hl-1">(</span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">processed</span><span class="hl-1">, </span><span class="hl-2">batchSize</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">item</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">items</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">processItem</span><span class="hl-1">(</span><span class="hl-2">item</span><span class="hl-1">); </span><span class="hl-7">// Makes ~10 requests per item</span><br/><span class="hl-1">    }</span><br/><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_progress&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">processed:</span><span class="hl-1"> </span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">processed</span><span class="hl-1"> + </span><span class="hl-2">batchSize</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">total:</span><span class="hl-1"> </span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">total</span><br/><span class="hl-1">    });</span><br/><br/><span class="hl-1">    </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">processed</span><span class="hl-1"> &lt; </span><span class="hl-2">progress</span><span class="hl-1">.</span><span class="hl-2">total</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-7">// Queue next batch - creates NEW execution with fresh request limit</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;processBatch&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">        </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">batchNumber</span><span class="hl-1"> + </span><span class="hl-14">1</span><br/><span class="hl-1">      });</span><br/><span class="hl-1">      </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">scheduleCleanup</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">tomorrow</span><span class="hl-1"> = </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">();</span><br/><span class="hl-1">    </span><span class="hl-2">tomorrow</span><span class="hl-1">.</span><span class="hl-6">setDate</span><span class="hl-1">(</span><span class="hl-2">tomorrow</span><span class="hl-1">.</span><span class="hl-6">getDate</span><span class="hl-1">() + </span><span class="hl-14">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;cleanupOldData&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-7">// Schedule for future execution</span><br/><span class="hl-1">    </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">, { </span><span class="hl-2">runAt:</span><span class="hl-1"> </span><span class="hl-2">tomorrow</span><span class="hl-1"> });</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
-</div></div></section><section class="tsd-panel tsd-hierarchy" data-refl="904"><h4>Hierarchy (<a href="../hierarchy.html#tools/tasks.Tasks">View Summary</a>)</h4><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><a href="tool.ITool.html" class="tsd-signature-type tsd-kind-class">ITool</a><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-hierarchy-target">Tasks</span></li></ul></li></ul></section><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L58">tools/tasks.ts:58</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h5 class="tsd-index-heading uppercase">Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Constructors</h3><div class="tsd-index-list"><a href="#constructor" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a>
+</div></div></section><section class="tsd-panel tsd-hierarchy" data-refl="907"><h4>Hierarchy (<a href="../hierarchy.html#tools/tasks.Tasks">View Summary</a>)</h4><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><a href="tool.ITool.html" class="tsd-signature-type tsd-kind-class">ITool</a><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-hierarchy-target">Tasks</span></li></ul></li></ul></section><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L82">tools/tasks.ts:82</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h5 class="tsd-index-heading uppercase">Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Constructors</h3><div class="tsd-index-list"><a href="#constructor" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a>
 </div></section><section class="tsd-index-section"><h3 class="tsd-index-heading">Methods</h3><div class="tsd-index-list"><a href="#runtask" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>run<wbr/>Task</span></a>
 <a href="#canceltask" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>cancel<wbr/>Task</span></a>
 <a href="#cancelalltasks" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>cancel<wbr/>All<wbr/>Tasks</span></a>
-</div></section></div></details></section></section><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Constructors"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h2>Constructors</h2></summary><section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="constructor"><span>constructor</span><a href="#constructor" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="constructortasks"><span class="tsd-signature-keyword">new</span> <span class="tsd-kind-constructor-signature">Tasks</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <a href="" class="tsd-signature-type tsd-kind-class">Tasks</a><a href="#constructortasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><h4 class="tsd-returns-title">Returns <a href="" class="tsd-signature-type tsd-kind-class">Tasks</a></h4><aside class="tsd-sources"><p>Inherited from <a href="tool.ITool.html">ITool</a>.<a href="tool.ITool.html#constructor">constructor</a></p></aside></div></li></ul></section></section></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Methods"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h2>Methods</h2></summary><section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="runtask"><code class="tsd-tag">Abstract</code><span>run<wbr/>Task</span><a href="#runtask" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="runtask-1"><span class="tsd-kind-call-signature">runTask</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">callback</span><span class="tsd-signature-symbol">:</span> <a href="../types/tools_callbacks.Callback.html" class="tsd-signature-type tsd-kind-type-alias">Callback</a><span class="tsd-signature-symbol">,</span> <span class="tsd-kind-parameter">options</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">runAt</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">Date</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span><a href="#runtask-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Queues a callback to execute in a separate worker context.</p>
+</div></section></div></details></section></section><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Constructors"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h2>Constructors</h2></summary><section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="constructor"><span>constructor</span><a href="#constructor" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="constructortasks"><span class="tsd-signature-keyword">new</span> <span class="tsd-kind-constructor-signature">Tasks</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <a href="" class="tsd-signature-type tsd-kind-class">Tasks</a><a href="#constructortasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><h4 class="tsd-returns-title">Returns <a href="" class="tsd-signature-type tsd-kind-class">Tasks</a></h4><aside class="tsd-sources"><p>Inherited from <a href="tool.ITool.html">ITool</a>.<a href="tool.ITool.html#constructor">constructor</a></p></aside></div></li></ul></section></section></details><details class="tsd-panel-group tsd-member-group tsd-accordion" open><summary class="tsd-accordion-summary" data-key="section-Methods"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h2>Methods</h2></summary><section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="runtask"><code class="tsd-tag">Abstract</code><span>run<wbr/>Task</span><a href="#runtask" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="runtask-1"><span class="tsd-kind-call-signature">runTask</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">callback</span><span class="tsd-signature-symbol">:</span> <a href="../types/tools_callbacks.Callback.html" class="tsd-signature-type tsd-kind-type-alias">Callback</a><span class="tsd-signature-symbol">,</span> <span class="tsd-kind-parameter">options</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">runAt</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">Date</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span><a href="#runtask-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Queues a callback to execute in a separate worker context with a fresh request limit.</p>
+<p><strong>Creates a NEW execution</strong> with its own request limit of ~1000 requests (HTTP requests,
+tool calls, database operations). This is the primary way to stay under request limits
+when processing large datasets or making many API calls.</p>
 <p>The callback will be invoked either immediately or at a scheduled time
-in an isolated execution environment with limited resources. Use this
-for breaking up long-running operations into manageable chunks.</p>
+in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds
+CPU time. Use this for breaking loops into chunks that stay under the request limit.</p>
+<p><strong>Key distinction:</strong></p>
+<ul>
+<li><code>this.run(callback)</code> - Continues same execution, shares request count</li>
+<li><code>this.runTask(callback)</code> - NEW execution, fresh request limit</li>
+</ul>
 </div><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">callback</span>: <a href="../types/tools_callbacks.Callback.html" class="tsd-signature-type tsd-kind-type-alias">Callback</a></span><div class="tsd-comment tsd-typography"><p>Callback created with <code>this.callback()</code></p>
 </div></li><li><span><code class="tsd-tag">Optional</code><span class="tsd-kind-parameter">options</span>: <span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">runAt</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">Date</span> <span class="tsd-signature-symbol">}</span></span><div class="tsd-comment tsd-typography"><p>Optional configuration for the execution</p>
 </div><ul class="tsd-parameters"><li class="tsd-parameter"><h5><code class="tsd-tag">Optional</code><span class="tsd-kind-property">runAt</span><span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">Date</span></h5><div class="tsd-comment tsd-typography"><p>If provided, schedules execution at this time; otherwise runs immediately</p>
 </div></li></ul></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span></h4><p>Promise resolving to a cancellation token (only for scheduled executions)</p>
-<aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L72">tools/tasks.ts:72</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="canceltask"><code class="tsd-tag">Abstract</code><span>cancel<wbr/>Task</span><a href="#canceltask" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="canceltask-1"><span class="tsd-kind-call-signature">cancelTask</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">token</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span><a href="#canceltask-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Cancels a previously scheduled execution.</p>
+<div class="tsd-comment tsd-typography"><div class="tsd-tag-example"><h4 class="tsd-anchor-link" id="example-1">Example<a href="#example-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript"><span class="hl-7">// Break large loop into batches to stay under request limit</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1"> });</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">); </span><span class="hl-7">// Fresh execution with ~1000 requests</span>
+</code><button type="button">Copy</button></pre>
+</div></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L111">tools/tasks.ts:111</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="canceltask"><code class="tsd-tag">Abstract</code><span>cancel<wbr/>Task</span><a href="#canceltask" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="canceltask-1"><span class="tsd-kind-call-signature">cancelTask</span><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">token</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span><a href="#canceltask-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Cancels a previously scheduled execution.</p>
 <p>Prevents a scheduled function from executing. No error is thrown
 if the token is invalid or the execution has already completed.</p>
 </div><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">token</span>: <span class="tsd-signature-type">string</span></span><div class="tsd-comment tsd-typography"><p>The cancellation token returned by runTask() with runAt option</p>
 </div></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span></h4><p>Promise that resolves when the cancellation is processed</p>
-<aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L87">tools/tasks.ts:87</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="cancelalltasks"><code class="tsd-tag">Abstract</code><span>cancel<wbr/>All<wbr/>Tasks</span><a href="#cancelalltasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="cancelalltasks-1"><span class="tsd-kind-call-signature">cancelAllTasks</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span><a href="#cancelalltasks-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Cancels all scheduled executions for this tool/twist.</p>
+<aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L126">tools/tasks.ts:126</a></li></ul></aside></div></li></ul></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="cancelalltasks"><code class="tsd-tag">Abstract</code><span>cancel<wbr/>All<wbr/>Tasks</span><a href="#cancelalltasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ul class="tsd-signatures"><li class=""><div class="tsd-signature tsd-anchor-link" id="cancelalltasks-1"><span class="tsd-kind-call-signature">cancelAllTasks</span><span class="tsd-signature-symbol">()</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span><a href="#cancelalltasks-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></div><div class="tsd-description"><div class="tsd-comment tsd-typography"><p>Cancels all scheduled executions for this tool/twist.</p>
 <p>Cancels all pending scheduled executions created by this tool or twist
 instance. Immediate executions cannot be cancelled.</p>
 </div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span></h4><p>Promise that resolves when all cancellations are processed</p>
-<aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L97">tools/tasks.ts:97</a></li></ul></aside></div></li></ul></section></section></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Constructors"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Constructors</summary><div><a href="#constructor"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Methods"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Methods</summary><div><a href="#runtask"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>run<wbr/>Task</span></a><a href="#canceltask"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>cancel<wbr/>Task</span></a><a href="#cancelalltasks"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>cancel<wbr/>All<wbr/>Tasks</span></a></div></details></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+<aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/tasks.ts#L136">tools/tasks.ts:136</a></li></ul></aside></div></li></ul></section></section></details></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Constructors"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Constructors</summary><div><a href="#constructor"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a></div></details><details open class="tsd-accordion tsd-page-navigation-section"><summary class="tsd-accordion-summary" data-key="section-Methods"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg>Methods</summary><div><a href="#runtask"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>run<wbr/>Task</span></a><a href="#canceltask"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>cancel<wbr/>Task</span></a><a href="#cancelalltasks"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>cancel<wbr/>All<wbr/>Tasks</span></a></div></details></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>

package/dist/docs/classes/tools_twists.Twists.html CHANGED Viewed

@@ -4,7 +4,7 @@ and programmatically deploy twists.</p>
 </div><div class="tsd-comment tsd-typography"><div class="tsd-tag-example"><h4 class="tsd-anchor-link" id="example">Example<a href="#example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="typescript"><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">TwistBuilderTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ToolBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1">   </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1">     </span><span class="hl-2">twists:</span><span class="hl-1"> </span><span class="hl-2">build</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">Twists</span><span class="hl-1">)</span><br/><span class="hl-1">   }</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">twistId</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">twists</span><span class="hl-1">.</span><span class="hl-6">create</span><span class="hl-1">();</span><br/><span class="hl-1">    </span><span class="hl-7">// Display twist ID to user</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
-</div></div></section><section class="tsd-panel tsd-hierarchy" data-refl="444"><h4>Hierarchy (<a href="../hierarchy.html#tools/twists.Twists">View Summary</a>)</h4><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><a href="tool.ITool.html" class="tsd-signature-type tsd-kind-class">ITool</a><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-hierarchy-target">Twists</span></li></ul></li></ul></section><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/twists.ts#L78">tools/twists.ts:78</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h5 class="tsd-index-heading uppercase">Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Constructors</h3><div class="tsd-index-list"><a href="#constructor" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a>
+</div></div></section><section class="tsd-panel tsd-hierarchy" data-refl="447"><h4>Hierarchy (<a href="../hierarchy.html#tools/twists.Twists">View Summary</a>)</h4><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><a href="tool.ITool.html" class="tsd-signature-type tsd-kind-class">ITool</a><ul class="tsd-hierarchy"><li class="tsd-hierarchy-item"><span class="tsd-hierarchy-target">Twists</span></li></ul></li></ul></section><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/plotday/plot/blob/main/twist/twister/src/tools/twists.ts#L78">tools/twists.ts:78</a></li></ul></aside><section class="tsd-panel-group tsd-index-group"><section class="tsd-panel tsd-index-panel"><details class="tsd-index-content tsd-accordion" open><summary class="tsd-accordion-summary tsd-index-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h5 class="tsd-index-heading uppercase">Index</h5></summary><div class="tsd-accordion-details"><section class="tsd-index-section"><h3 class="tsd-index-heading">Constructors</h3><div class="tsd-index-list"><a href="#constructor" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Constructor"><use href="../assets/icons.svg#icon-512"></use></svg><span>constructor</span></a>
 </div></section><section class="tsd-index-section"><h3 class="tsd-index-heading">Methods</h3><div class="tsd-index-list"><a href="#create" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>create</span></a>
 <a href="#generate" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>generate</span></a>
 <a href="#deploy" class="tsd-index-link"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Method"><use href="../assets/icons.svg#icon-2048"></use></svg><span>deploy</span></a>

package/dist/docs/documents/Building_Custom_Tools.html CHANGED Viewed

@@ -86,9 +86,19 @@
 <li>Final initialization</li>
 </ul>
 <h3 id="preupgrade" class="tsd-anchor-link">preUpgrade()<a href="#preupgrade" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called <strong>before</strong> the twist's <code>upgrade()</code> method.</p>
+<p><strong>Use for:</strong></p>
+<ul>
+<li>Preparing data migrations</li>
+<li>Checking tool version compatibility</li>
+<li>Handling breaking changes to callback signatures</li>
+</ul>
 <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">preUpgrade</span><span class="hl-1">(): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">// Prepare for upgrade</span><br/><span class="hl-1">  const </span><span class="hl-2">version</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;tool_version&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-6">if</span><span class="hl-1"> (</span><span class="hl-2">version</span><span class="hl-1"> === </span><span class="hl-3">&quot;1.0.0&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Migrate data</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
+<p><strong>IMPORTANT:</strong> Tool callbacks automatically upgrade to the new version. Callbacks are resolved by function name at execution time, so callbacks created in v1.0 will use v2.0's code after upgrade. Maintain backward compatibility in callback signatures or recreate callbacks in <code>preUpgrade()</code>:</p>
+<pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">preUpgrade</span><span class="hl-1">(): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  const </span><span class="hl-2">version</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;tool_version&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-6">if</span><span class="hl-1"> (</span><span class="hl-2">version</span><span class="hl-1"> === </span><span class="hl-3">&quot;1.0.0&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Handle breaking change: recreate callbacks with new signature</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">syncs</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">[]&gt;(</span><span class="hl-3">&quot;active_syncs&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">syncId</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">syncs</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-7">// Delete old callback</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">oldCallback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">`sync_</span><span class="hl-4">${</span><span class="hl-2">syncId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">oldCallback</span><span class="hl-1">) </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">deleteCallback</span><span class="hl-1">(</span><span class="hl-2">oldCallback</span><span class="hl-1">);</span><br/><br/><span class="hl-1">      </span><span class="hl-7">// Create new callback with updated signature</span><br/><span class="hl-1">      </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">newCallback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatchV2&quot;</span><span class="hl-1">, </span><span class="hl-2">syncId</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_</span><span class="hl-4">${</span><span class="hl-2">syncId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">newCallback</span><span class="hl-1">);</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
 <h3 id="postupgrade" class="tsd-anchor-link">postUpgrade()<a href="#postupgrade" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called <strong>after</strong> the twist's <code>upgrade()</code> method.</p>
 <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">postUpgrade</span><span class="hl-1">(): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">// Finalize upgrade</span><br/><span class="hl-1">  await this.set(</span><span class="hl-3">&quot;tool_version&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;2.0.0&quot;</span><span class="hl-2">);</span><br/><span class="hl-2">}</span>
 </code><button type="button">Copy</button></pre>

package/dist/docs/documents/Built-in_Tools.html CHANGED Viewed

@@ -104,7 +104,13 @@
 </code><button type="button">Copy</button></pre>
 <hr>
-<h2 id="tasks" class="tsd-anchor-link">Tasks<a href="#tasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Queue background tasks and schedule operations. Tasks methods are available directly on the twist class.</p>
+<h2 id="tasks" class="tsd-anchor-link">Tasks<a href="#tasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Queue background tasks and schedule operations. <strong>Critical for staying under request limits</strong>: each execution has ~1000 requests (HTTP requests, tool calls, database operations), and running a task creates a NEW execution with a fresh request limit.</p>
+<p><strong>Key distinction:</strong></p>
+<ul>
+<li><strong>Calling a callback</strong> (via <code>this.run()</code>) continues the same execution and shares the request count</li>
+<li><strong>Running a task</strong> (via <code>this.runTask()</code>) creates a NEW execution with fresh ~1000 request limit</li>
+</ul>
+<p>Tasks methods are available directly on the twist class.</p>
 <h3 id="setup-3" class="tsd-anchor-link">Setup<a href="#setup-3" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Tasks are available automatically - no build() declaration needed!</p>
 <h3 id="running-tasks-immediately" class="tsd-anchor-link">Running Tasks Immediately<a href="#running-tasks-immediately" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Create a callback</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;processData&quot;</span><span class="hl-1">, { </span><span class="hl-2">batchId:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1"> });</span><br/><br/><span class="hl-7">// Run immediately</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// The processData method will be called</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">processData</span><span class="hl-1">(</span><span class="hl-2">args</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">batchId:</span><span class="hl-1"> </span><span class="hl-2">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1">  </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Processing batch:&quot;</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">batchId</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
@@ -115,8 +121,8 @@
 <h3 id="canceling-tasks" class="tsd-anchor-link">Canceling Tasks<a href="#canceling-tasks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Cancel a specific task</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">token</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;reminder_token&quot;</span><span class="hl-1">);</span><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">token</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">cancelTask</span><span class="hl-1">(</span><span class="hl-2">token</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// Cancel all scheduled tasks for this twist</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">cancelAllTasks</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
-<h3 id="batch-processing-pattern" class="tsd-anchor-link">Batch Processing Pattern<a href="#batch-processing-pattern" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Use tasks to break long operations into manageable chunks:</p>
-<pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startSync</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-7">// Initialize state</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">    </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Start first batch</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;{ </span><span class="hl-2">page</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">; </span><span class="hl-2">hasMore</span><span class="hl-1">: </span><span class="hl-5">boolean</span><span class="hl-1"> }&gt;(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1"> || !</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">hasMore</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Process one page</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">results</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">fetchPage</span><span class="hl-1">(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">processResults</span><span class="hl-1">(</span><span class="hl-2">results</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Check if more work remains</span><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">results</span><span class="hl-1">.</span><span class="hl-2">hasMore</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1">    });</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// Queue next batch</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">  } </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">, </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> });</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<h3 id="batch-processing-pattern" class="tsd-anchor-link">Batch Processing Pattern<a href="#batch-processing-pattern" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Use tasks to break long operations into chunks that stay under the ~1000 request limit per execution:</p>
+<pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startSync</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-7">// Initialize state</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">    </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Start first batch</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-7">// runTask creates NEW execution with fresh request limit</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;{ </span><span class="hl-2">page</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">; </span><span class="hl-2">hasMore</span><span class="hl-1">: </span><span class="hl-5">boolean</span><span class="hl-1"> }&gt;(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1"> || !</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">hasMore</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Process one page (sized to stay under request limit)</span><br/><span class="hl-1">  </span><span class="hl-7">// If each item makes ~10 requests, fetch ~100 items per page</span><br/><span class="hl-1">  </span><span class="hl-7">// 100 items × 10 requests = 1000 requests (at limit)</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">results</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">fetchPage</span><span class="hl-1">(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">, </span><span class="hl-14">100</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">processResults</span><span class="hl-1">(</span><span class="hl-2">results</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// Check if more work remains</span><br/><span class="hl-1">  </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">results</span><span class="hl-1">.</span><span class="hl-2">hasMore</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1">      </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1">    });</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// Queue next batch - creates NEW execution with fresh request limit</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatch&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">  } </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">, </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> });</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 <p>See <a href="Runtime_Environment.html">Runtime Environment</a> for more about handling long operations.</p>
@@ -148,6 +154,35 @@
 <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">handleEvent</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-2">args</span><span class="hl-1">: { </span><span class="hl-2">data:</span><span class="hl-1"> </span><span class="hl-2">any</span><span class="hl-1">; </span><span class="hl-2">timestamp</span><span class="hl-1">: </span><span class="hl-2">Date</span><span class="hl-1"> },      </span><span class="hl-7">// From run()</span><br/><span class="hl-1">  </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">eventType:</span><span class="hl-1"> </span><span class="hl-2">string</span><span class="hl-1">; </span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1"> }  </span><span class="hl-7">// From callback()</span><br/><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Event type:&quot;</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">eventType</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Priority:&quot;</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">priority</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Data:&quot;</span><span class="hl-1">, </span><span class="hl-2">args</span><span class="hl-1">.</span><span class="hl-2">data</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
+<h3 id="callback-versioning-and-upgrades" class="tsd-anchor-link">Callback Versioning and Upgrades<a href="#callback-versioning-and-upgrades" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p><strong>CRITICAL:</strong> Callbacks automatically upgrade to new twist versions when you deploy an update. This means:</p>
+<ul>
+<li>Callbacks created before an upgrade will execute using the <strong>new version's code</strong></li>
+<li>The callback is resolved <strong>by function name</strong> at execution time, not at creation time</li>
+<li>You can receive calls with arguments from the previous version running on the new version</li>
+</ul>
+<h4 id="handling-version-transitions" class="tsd-anchor-link">Handling Version Transitions<a href="#handling-version-transitions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p>You have two options when deploying a new version with callback changes:</p>
+<p><strong>Option 1: Maintain Backward Compatibility</strong> (Recommended)</p>
+<pre><code class="typescript"><span class="hl-7">// v1.0 - Original signature</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">batchNumber</span><span class="hl-1">: </span><span class="hl-2">number</span><span class="hl-1">, </span><span class="hl-2">authToken</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">, </span><span class="hl-2">calendarId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// Process batch</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// v1.1 - Add optional parameter at the end</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-2">batchNumber</span><span class="hl-1">: </span><span class="hl-2">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">authToken</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">calendarId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">initialSync</span><span class="hl-1">?: </span><span class="hl-2">boolean</span><span class="hl-1">  </span><span class="hl-7">// New optional parameter</span><br/><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">isInitial</span><span class="hl-1"> = </span><span class="hl-2">initialSync</span><span class="hl-1"> ?? </span><span class="hl-4">true</span><span class="hl-1">;  </span><span class="hl-7">// Safe default for old calls</span><br/><span class="hl-1">  </span><span class="hl-7">// Process batch with new logic</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Option 2: Maintain Old Function Temporarily</strong></p>
+<p>For breaking changes, keep the old function and create a new one:</p>
+<pre><code class="typescript"><span class="hl-7">// v2.0 - Keep old function for in-flight callbacks</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">batchNumber</span><span class="hl-1">: </span><span class="hl-2">number</span><span class="hl-1">, </span><span class="hl-2">authToken</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">, </span><span class="hl-2">calendarId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// Old implementation still works for callbacks created in v1.x</span><br/><span class="hl-1">  </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">processOldBatch</span><span class="hl-1">(</span><span class="hl-2">batchNumber</span><span class="hl-1">, </span><span class="hl-2">authToken</span><span class="hl-1">, </span><span class="hl-2">calendarId</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// New function with better design</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatchV2</span><span class="hl-1">(</span><span class="hl-2">options</span><span class="hl-1">: </span><span class="hl-2">SyncOptions</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// New implementation</span><br/><span class="hl-1">  </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">processNewBatch</span><span class="hl-1">(</span><span class="hl-2">options</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// Later in v3.0 - Remove old function once all callbacks complete</span><br/><span class="hl-7">// async syncBatch - REMOVED</span>
+</code><button type="button">Copy</button></pre>
+<h4 id="affected-callback-types" class="tsd-anchor-link">Affected Callback Types<a href="#affected-callback-types" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p>This versioning behavior applies to ALL callbacks:</p>
+<ul>
+<li><strong>Webhooks</strong> - Long-lived, called by external services</li>
+<li><strong>Scheduled tasks</strong> - Created with <code>runTask()</code>, may run days later</li>
+<li><strong>Batch operations</strong> - Multi-step processes that span upgrades</li>
+<li><strong>Activity link callbacks</strong> - Interactive buttons in activities</li>
+<li><strong>Auth callbacks</strong> - OAuth completion handlers</li>
+</ul>
+<h4 id="migration-in-upgrade" class="tsd-anchor-link">Migration in upgrade()<a href="#migration-in-upgrade" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4><p>For breaking changes, you can recreate callbacks in the <code>upgrade()</code> lifecycle method:</p>
+<pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">upgrade</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-7">// Get all active syncs that use old callback signature</span><br/><span class="hl-1">  </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">syncs</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">SyncState</span><span class="hl-1">[]&gt;(</span><span class="hl-3">&quot;active_syncs&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">sync</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">syncs</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// Cancel old callback</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">oldCallback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">`sync_callback_</span><span class="hl-4">${</span><span class="hl-2">sync</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">oldCallback</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">deleteCallback</span><span class="hl-1">(</span><span class="hl-2">oldCallback</span><span class="hl-1">);</span><br/><span class="hl-1">    }</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// Create new callback with updated signature</span><br/><span class="hl-1">    </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">newCallback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-3">&quot;syncBatchV2&quot;</span><span class="hl-1">, </span><span class="hl-2">sync</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_callback_</span><span class="hl-4">${</span><span class="hl-2">sync</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">newCallback</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Important:</strong> If you don't handle breaking changes, existing callbacks may fail when they execute with incompatible arguments.</p>
 <h3 id="deleting-callbacks" class="tsd-anchor-link">Deleting Callbacks<a href="#deleting-callbacks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Delete a specific callback</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;event_handler&quot;</span><span class="hl-1">);</span><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">callback</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">deleteCallback</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// Delete all callbacks for this twist</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">deleteAllCallbacks</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
@@ -197,4 +232,4 @@
 <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understanding execution constraints</li>
 <li><strong>API Reference</strong> - Explore detailed API docs in the sidebar</li>
 </ul>
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#built-in-tools"><span>Built-<wbr/>in <wbr/>Tools</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#plot"><span>Plot</span></a></li><li><ul><li><a href="#understanding-activities-and-notes"><span>Understanding <wbr/>Activities and <wbr/>Notes</span></a></li><li><a href="#setup"><span>Setup</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><ul><li><a href="#action-scheduling-states"><span>Action <wbr/>Scheduling <wbr/>States</span></a></li></ul></li><li><a href="#updating-activities"><span>Updating <wbr/>Activities</span></a></li><li><a href="#deleting-activities"><span>Deleting <wbr/>Activities</span></a></li><li><a href="#managing-priorities"><span>Managing <wbr/>Priorities</span></a></li><li><a href="#activity-data-synchronization"><span>Activity <wbr/>Data <wbr/>Synchronization</span></a></li><li><a href="#creating-and-managing-notes"><span>Creating and <wbr/>Managing <wbr/>Notes</span></a></li><li><ul><li><a href="#creating-notes-on-new-activities"><span>Creating <wbr/>Notes on <wbr/>New <wbr/>Activities</span></a></li><li><a href="#adding-notes-to-existing-activities"><span>Adding <wbr/>Notes to <wbr/>Existing <wbr/>Activities</span></a></li><li><a href="#pattern-email-threads-and-conversations"><span>Pattern: <wbr/>Email <wbr/>Threads and <wbr/>Conversations</span></a></li></ul></li></ul></li><li><a href="#store"><span>Store</span></a></li><li><ul><li><a href="#setup-1"><span>Setup</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#retrieving-data"><span>Retrieving <wbr/>Data</span></a></li><li><a href="#clearing-data"><span>Clearing <wbr/>Data</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#type-safety"><span>Type <wbr/>Safety</span></a></li><li><a href="#namespacing"><span>Namespacing</span></a></li><li><a href="#serialization-limits"><span>Serialization <wbr/>Limits</span></a></li></ul></li></ul></li><li><a href="#integrations"><span>Integrations</span></a></li><li><ul><li><a href="#setup-2"><span>Setup</span></a></li><li><a href="#requesting-authentication"><span>Requesting <wbr/>Authentication</span></a></li><li><a href="#auth-providers"><span>Auth <wbr/>Providers</span></a></li><li><a href="#auth-levels"><span>Auth <wbr/>Levels</span></a></li><li><a href="#using-auth-tokens"><span>Using <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#tasks"><span>Tasks</span></a></li><li><ul><li><a href="#setup-3"><span>Setup</span></a></li><li><a href="#running-tasks-immediately"><span>Running <wbr/>Tasks <wbr/>Immediately</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#canceling-tasks"><span>Canceling <wbr/>Tasks</span></a></li><li><a href="#batch-processing-pattern"><span>Batch <wbr/>Processing <wbr/>Pattern</span></a></li></ul></li><li><a href="#network"><span>Network</span></a></li><li><ul><li><a href="#setup-4"><span>Setup</span></a></li><li><a href="#making-http-requests"><span>Making <wbr/>HTTP <wbr/>Requests</span></a></li><li><a href="#creating-webhooks"><span>Creating <wbr/>Webhooks</span></a></li><li><a href="#deleting-webhooks"><span>Deleting <wbr/>Webhooks</span></a></li></ul></li><li><a href="#callbacks"><span>Callbacks</span></a></li><li><ul><li><a href="#setup-5"><span>Setup</span></a></li><li><a href="#creating-callbacks"><span>Creating <wbr/>Callbacks</span></a></li><li><a href="#executing-callbacks"><span>Executing <wbr/>Callbacks</span></a></li><li><a href="#method-signature"><span>Method <wbr/>Signature</span></a></li><li><a href="#deleting-callbacks"><span>Deleting <wbr/>Callbacks</span></a></li><li><a href="#use-cases"><span>Use <wbr/>Cases</span></a></li></ul></li><li><a href="#ai"><span>AI</span></a></li><li><ul><li><a href="#setup-6"><span>Setup</span></a></li><li><a href="#simple-text-generation"><span>Simple <wbr/>Text <wbr/>Generation</span></a></li><li><a href="#structured-output"><span>Structured <wbr/>Output</span></a></li><li><a href="#tool-calling"><span>Tool <wbr/>Calling</span></a></li><li><a href="#multi-turn-conversations"><span>Multi-<wbr/>turn <wbr/>Conversations</span></a></li><li><a href="#model-selection"><span>Model <wbr/>Selection</span></a></li><li><a href="#typebox-schemas"><span>Typebox <wbr/>Schemas</span></a></li><li><a href="#real-world-example-email-triage"><span>Real-<wbr/>World <wbr/>Example: <wbr/>Email <wbr/>Triage</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#built-in-tools"><span>Built-<wbr/>in <wbr/>Tools</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#plot"><span>Plot</span></a></li><li><ul><li><a href="#understanding-activities-and-notes"><span>Understanding <wbr/>Activities and <wbr/>Notes</span></a></li><li><a href="#setup"><span>Setup</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><ul><li><a href="#action-scheduling-states"><span>Action <wbr/>Scheduling <wbr/>States</span></a></li></ul></li><li><a href="#updating-activities"><span>Updating <wbr/>Activities</span></a></li><li><a href="#deleting-activities"><span>Deleting <wbr/>Activities</span></a></li><li><a href="#managing-priorities"><span>Managing <wbr/>Priorities</span></a></li><li><a href="#activity-data-synchronization"><span>Activity <wbr/>Data <wbr/>Synchronization</span></a></li><li><a href="#creating-and-managing-notes"><span>Creating and <wbr/>Managing <wbr/>Notes</span></a></li><li><ul><li><a href="#creating-notes-on-new-activities"><span>Creating <wbr/>Notes on <wbr/>New <wbr/>Activities</span></a></li><li><a href="#adding-notes-to-existing-activities"><span>Adding <wbr/>Notes to <wbr/>Existing <wbr/>Activities</span></a></li><li><a href="#pattern-email-threads-and-conversations"><span>Pattern: <wbr/>Email <wbr/>Threads and <wbr/>Conversations</span></a></li></ul></li></ul></li><li><a href="#store"><span>Store</span></a></li><li><ul><li><a href="#setup-1"><span>Setup</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#retrieving-data"><span>Retrieving <wbr/>Data</span></a></li><li><a href="#clearing-data"><span>Clearing <wbr/>Data</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#type-safety"><span>Type <wbr/>Safety</span></a></li><li><a href="#namespacing"><span>Namespacing</span></a></li><li><a href="#serialization-limits"><span>Serialization <wbr/>Limits</span></a></li></ul></li></ul></li><li><a href="#integrations"><span>Integrations</span></a></li><li><ul><li><a href="#setup-2"><span>Setup</span></a></li><li><a href="#requesting-authentication"><span>Requesting <wbr/>Authentication</span></a></li><li><a href="#auth-providers"><span>Auth <wbr/>Providers</span></a></li><li><a href="#auth-levels"><span>Auth <wbr/>Levels</span></a></li><li><a href="#using-auth-tokens"><span>Using <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#tasks"><span>Tasks</span></a></li><li><ul><li><a href="#setup-3"><span>Setup</span></a></li><li><a href="#running-tasks-immediately"><span>Running <wbr/>Tasks <wbr/>Immediately</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#canceling-tasks"><span>Canceling <wbr/>Tasks</span></a></li><li><a href="#batch-processing-pattern"><span>Batch <wbr/>Processing <wbr/>Pattern</span></a></li></ul></li><li><a href="#network"><span>Network</span></a></li><li><ul><li><a href="#setup-4"><span>Setup</span></a></li><li><a href="#making-http-requests"><span>Making <wbr/>HTTP <wbr/>Requests</span></a></li><li><a href="#creating-webhooks"><span>Creating <wbr/>Webhooks</span></a></li><li><a href="#deleting-webhooks"><span>Deleting <wbr/>Webhooks</span></a></li></ul></li><li><a href="#callbacks"><span>Callbacks</span></a></li><li><ul><li><a href="#setup-5"><span>Setup</span></a></li><li><a href="#creating-callbacks"><span>Creating <wbr/>Callbacks</span></a></li><li><a href="#executing-callbacks"><span>Executing <wbr/>Callbacks</span></a></li><li><a href="#method-signature"><span>Method <wbr/>Signature</span></a></li><li><a href="#callback-versioning-and-upgrades"><span>Callback <wbr/>Versioning and <wbr/>Upgrades</span></a></li><li><ul><li><a href="#handling-version-transitions"><span>Handling <wbr/>Version <wbr/>Transitions</span></a></li><li><a href="#affected-callback-types"><span>Affected <wbr/>Callback <wbr/>Types</span></a></li><li><a href="#migration-in-upgrade"><span>Migration in upgrade()</span></a></li></ul></li><li><a href="#deleting-callbacks"><span>Deleting <wbr/>Callbacks</span></a></li><li><a href="#use-cases"><span>Use <wbr/>Cases</span></a></li></ul></li><li><a href="#ai"><span>AI</span></a></li><li><ul><li><a href="#setup-6"><span>Setup</span></a></li><li><a href="#simple-text-generation"><span>Simple <wbr/>Text <wbr/>Generation</span></a></li><li><a href="#structured-output"><span>Structured <wbr/>Output</span></a></li><li><a href="#tool-calling"><span>Tool <wbr/>Calling</span></a></li><li><a href="#multi-turn-conversations"><span>Multi-<wbr/>turn <wbr/>Conversations</span></a></li><li><a href="#model-selection"><span>Model <wbr/>Selection</span></a></li><li><a href="#typebox-schemas"><span>Typebox <wbr/>Schemas</span></a></li><li><a href="#real-world-example-email-triage"><span>Real-<wbr/>World <wbr/>Example: <wbr/>Email <wbr/>Triage</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>