@plotday/twister 0.56.0 → 0.58.0

package/cli/templates/AGENTS.template.md

@@ -29,17 +29,18 @@ Plot Twists are TypeScript classes that extend the `Twist` base class. Twists in
 
 1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes
 2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message
-3. **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.
+3. **Use source/key for automatic upserts (Recommended)** - External items are saved as links keyed by `source` (connectors call `integrations.saveLink()` with the item's canonical URL/ID), and `Note.key` enables upsertable note content. Reference an already-synced thread with `thread: { source }`. No manual ID tracking needed.
 4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)
-5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`
+5. **Thread `type` is an optional display sub-type** - One of `"action"`, `"notes"`, `"idea"`, `"goal"`, `"decision"`, `"discussion"`, `"announcement"`, `"ask"`. Omit it for the default (`"notes"` in private focuses, `"discussion"` in shared ones). Use `"action"` for tasks; events are threads with `schedules`.
 
 ### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)
 
 ```
 New event/task/conversation from external system?
   ├─ Has stable URL or ID?
-  │   └─ Yes → Set Thread.source to the canonical URL/ID
-  │             Create Thread (Plot handles deduplication automatically)
+  │   └─ Yes → Save a link with `source` set to the canonical URL/ID
+  │             (connectors: integrations.saveLink() — Plot handles
+  │             deduplication automatically)
   │             Use Note.key for different note types:
   │               - "description" for main content
   │               - "metadata" for status/priority/assignee
@@ -71,11 +72,9 @@ New event/task/conversation?
 import {
   type Thread,
   type NewThreadWithNotes,
-  type ThreadFilter,
-  type Priority,
+  type Note,
   type ToolBuilder,
   Twist,
-  ThreadType,
 } from "@plotday/twister";
 import { ThreadAccess, Plot } from "@plotday/twister/tools/plot";
 // Import your sources or tools as needed
@@ -89,7 +88,7 @@ export default class MyTwist extends Twist<MyTwist> {
     };
   }
 
-  async activate(_priority: Pick<Priority, "id">) {
+  async activate() {
     // Auth and resource selection handled in the twist edit modal.
   }
 }
@@ -119,11 +118,11 @@ For complete API documentation of built-in tools including all methods, types, a
 
 **Quick reference - Available tools:**
 
-- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)
+- `@plotday/twister/tools/plot` - Core data layer (create/update threads, notes, focuses, contacts)
 - `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)
   - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)
 - `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)
-- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)
+- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.runTask()`)
 - `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)
 - `@plotday/twister/tools/integrations` - OAuth2 authentication flows
 - `@plotday/twister/tools/network` - HTTP access permissions and webhook management
@@ -133,25 +132,24 @@ For complete API documentation of built-in tools including all methods, types, a
 
 ## Lifecycle Methods
 
-### activate(priority: Pick<Priority, "id">)
+### activate(context?: { actor: Actor })
 
-Called when the twist is enabled for a priority. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.
+Called when the twist is installed by a user. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.
 
 Most twists have an empty or minimal `activate()`:
 
 ```typescript
-async activate(_priority: Pick<Priority, "id">) {
+async activate() {
   // Auth and resource selection are handled in the twist edit modal.
   // Only add custom initialization here if needed.
 }
 ```
 
-**Store Parent Thread for Later (optional):**
+**Store Setup Thread for Later (optional):**
 
 ```typescript
-async activate(_priority: Pick<Priority, "id">) {
+async activate() {
   const threadId = await this.tools.plot.createThread({
-    type: ThreadType.Note,
     title: "Setup complete",
     notes: [{
       content: "Your twist is ready. Threads will appear as they sync.",
@@ -161,9 +159,9 @@ async activate(_priority: Pick<Priority, "id">) {
 }
 ```
 
-### Event Callbacks (via build options)
+### Event Callbacks (lifecycle overrides)
 
-Twists respond to events through callbacks declared in `build()`:
+Twists respond to events by overriding lifecycle methods inherited from the `Twist` base class. No registration is needed — declare Plot access in `build()` and the runtime routes events for threads your twist created:
 
 **React to thread changes (for two-way sync):**
 
@@ -171,20 +169,19 @@ Twists respond to events through callbacks declared in `build()`:
 plot: build(Plot, {
   thread: {
     access: ThreadAccess.Create,
-    updated: this.onThreadUpdated,
-  },
-  note: {
-    created: this.onNoteCreated,
   },
 }),
 
-async onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {
-  const tool = this.getToolForThread(thread);
-  if (tool?.updateIssue) await tool.updateIssue(thread);
+// Called when a thread created by this twist is updated
+async onThreadUpdated(thread: Thread, changes: { tagsAdded: Record<Tag, ActorId[]>; tagsRemoved: Record<Tag, ActorId[]> }): Promise<void> {
+  // Push the change to the external system
+  await externalApi.updateItem(thread.meta?.externalId, { title: thread.title });
 }
 
+// Called when a note is created on a thread created by this twist.
+// Notes created by the twist itself are filtered out automatically.
 async onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
-  if (note.author.type === ActorType.Twist) return; // Prevent loops
+  if (note.author.type === ActorType.Twist) return; // Prevent loops with other twists
   // Sync note to external service as a comment. Return the external
   // system's id + stored content so the runtime can set note.key AND
   // record a sync baseline that preserves Plot's content on round-trip.
@@ -210,6 +207,8 @@ plot: build(Plot, {
 }),
 ```
 
+For a fully conversational twist, set `note.handler` instead of `intents` — every mention is then routed directly to that one method (`(note: Note) => Promise<void>`), skipping intent matching. `handler` and `intents` are mutually exclusive.
+
 **Default mention on replies:**
 
 When your twist processes replies (two-way comment sync or conversational AI), set `defaultMention: true` so the user doesn't have to manually re-mention your twist on every note:
@@ -218,15 +217,11 @@ When your twist processes replies (two-way comment sync or conversational AI), s
 - `note.defaultMention` — Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)
 
 ```typescript
-// Connector with two-way comment sync
+// Connector with two-way comment sync (override onThreadUpdated / onNoteCreated)
 plot: build(Plot, {
   thread: {
     access: ThreadAccess.Create,
     defaultMention: true,  // Users replying to synced threads will mention this twist by default
-    updated: this.onThreadUpdated,
-  },
-  note: {
-    created: this.onNoteCreated,
   },
 }),
 
@@ -256,8 +251,8 @@ const urlAction: Action = {
   url: "https://example.com",
 };
 
-// Callback action (uses Callbacks tool — use linkCallback, not callback)
-const token = await this.linkCallback(this.onActionClicked, "context");
+// Callback action (uses Callbacks tool — use actionCallback, not callback)
+const token = await this.actionCallback(this.onActionClicked, "context");
 const callbackAction: Action = {
   title: "Click me",
   type: ActionType.callback,
@@ -266,7 +261,6 @@ const callbackAction: Action = {
 
 // Add to thread note
 await this.tools.plot.createThread({
-  type: ThreadType.Note,
   title: "Task with actions",
   notes: [
     {
@@ -284,27 +278,40 @@ async onActionClicked(action: Action, context: string): Promise<void> {
 
 ## Authentication Pattern
 
-Auth is handled automatically via the Integrations tool. Tools declare their OAuth provider in `build()`, and users connect in the twist edit modal. **You do not need to create auth activities manually.**
+Auth is handled automatically via the Integrations tool. Connectors (twists that extend `Connector`) declare their OAuth provider and scopes as class properties, and users connect in the twist edit modal. **You do not need to create auth activities manually.**
 
 ```typescript
-// In your tool's build() method:
-build(build: ToolBuilder) {
-  return {
-    integrations: build(Integrations, {
-      providers: [{
-        provider: AuthProvider.Google,
-        scopes: ["https://www.googleapis.com/auth/calendar"],
-        getChannels: this.getChannels,          // List available resources after auth
-        onChannelEnabled: this.onChannelEnabled, // User enabled a resource
-        onChannelDisabled: this.onChannelDisabled, // User disabled a resource
-      }],
-    }),
-    // ...
-  };
+import { Connector, type ToolBuilder } from "@plotday/twister";
+import {
+  AuthProvider,
+  type AuthToken,
+  type Authorization,
+  type Channel,
+  Integrations,
+} from "@plotday/twister/tools/integrations";
+
+export default class MyConnector extends Connector<MyConnector> {
+  readonly provider = AuthProvider.Google;
+  readonly scopes = ["https://www.googleapis.com/auth/calendar"];
+
+  build(build: ToolBuilder) {
+    return {
+      integrations: build(Integrations),
+    };
+  }
+
+  // List available resources after auth
+  async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> { ... }
+
+  // User enabled a resource
+  async onChannelEnabled(channel: Channel): Promise<void> { ... }
+
+  // User disabled a resource
+  async onChannelDisabled(channel: Channel): Promise<void> { ... }
 }
 
 // Get a token for API calls:
-const token = await this.tools.integrations.get(AuthProvider.Google, channelId);
+const token = await this.tools.integrations.get(channelId);
 if (!token) throw new Error("No auth token available");
 const client = new ApiClient({ accessToken: token.token });
 ```
@@ -321,28 +328,33 @@ is not dispatched.
 
 ### Upsert via Source/Key (Strategy 2)
 
-Use source/key for automatic upserts:
+Use source/key for automatic upserts. Connectors save external items as links — `source` is the upsert key:
 
 ```typescript
 async handleEvent(event: ExternalEvent): Promise<void> {
-  const thread: NewThreadWithNotes = {
-    source: event.htmlLink,  // Canonical URL for automatic deduplication
-    type: ThreadType.Event,
+  // Create or update — Plot handles deduplication automatically
+  await this.tools.integrations.saveLink({
+    source: event.htmlLink,  // Canonical URL/ID for automatic deduplication
+    type: "event",
     title: event.summary || "(No title)",
-    notes: [],
-  };
+    notes: event.description
+      ? [{
+          key: "description",  // This key enables note-level upserts
+          content: event.description,
+        }]
+      : [],
+  });
+}
+```
 
-  if (event.description) {
-    thread.notes.push({
-      thread: { source: event.htmlLink },
-      key: "description",  // This key enables note-level upserts
-      content: event.description,
-    });
-  }
+`saveLink()` is available to Connectors only. A regular twist adding notes to an already-synced thread references it by source instead:
 
-  // Create or update — Plot handles deduplication automatically
-  await this.tools.plot.createThread(thread);
-}
+```typescript
+await this.tools.plot.createNote({
+  thread: { source: event.htmlLink },  // Reference the synced thread
+  key: "summary",
+  content: "...",
+});
 ```
 
 ### Advanced: Generate and Store IDs (Strategy 3)
@@ -391,10 +403,10 @@ async handleEventAdvanced(
 
 ## Resource Selection
 
-Resource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your tool's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.
+Resource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your connector's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.
 
 ```typescript
-// In your tool:
+// In your connector:
 async getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {
   const client = new ApiClient({ accessToken: token.token });
   const calendars = await client.listCalendars();
@@ -447,13 +459,11 @@ async syncBatch(resourceId: string): Promise<void> {
   // Process results using source/key pattern (automatic upserts, no manual tracking)
   // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit
   for (const item of result.items) {
-    // Each createThread may make ~5-10 requests depending on notes/links
-    await this.tools.plot.createThread({
+    await this.tools.integrations.saveLink({
       source: item.url, // Use item's canonical URL for automatic deduplication
-      type: ThreadType.Note,
+      type: "item",
       title: item.title,
       notes: [{
-        activity: { source: item.url },
         key: "description", // Use key for upsertable notes
         content: item.description,
       }],
@@ -461,6 +471,8 @@ async syncBatch(resourceId: string): Promise<void> {
       ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only
     });
   }
+  // Tip: integrations.saveLinks([...]) saves a whole page in one call,
+  // which counts as a single request against the execution budget.
 
   if (result.nextPageToken) {
     // Update state in Store for next batch
@@ -480,7 +492,6 @@ async syncBatch(resourceId: string): Promise<void> {
 
     // Optionally notify user of completion
     await this.tools.plot.createThread({
-      type: ThreadType.Note,
       title: "Sync complete",
       notes: [
         {
@@ -507,25 +518,25 @@ All sync-based tools should distinguish between initial sync (first import) and
 
 **Example:**
 ```typescript
-const thread: NewThread = {
-  type: ThreadType.Event,
+await this.tools.integrations.saveLink({
   source: event.url,
+  type: "event",
   title: event.title,
   ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental
   ...(initialSync ? { archived: false } : {}),    // unarchive on initial only
-};
+});
 ```
 
 **Why this matters:**
-- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports
-- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved
-- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)
+- **Initial sync**: Threads are unarchived and marked as read for all users, preventing spam from bulk historical imports
+- **Incremental sync**: Threads are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved
+- **Reinstall**: Acts as initial sync, so previously archived threads are unarchived (fresh start)
 
 ### Two-Way Sync: Avoiding Race Conditions
 
 When implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Thread/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.
 
-**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Thread.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.
+**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.
 
 ```typescript
 async pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {
@@ -546,15 +557,21 @@ async pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {
 async onWebhook(payload: WebhookPayload): Promise<void> {
   const comment = payload.comment;
 
-  // Use Plot ID from metadata if present (handles race condition),
-  // otherwise fall back to upserting by activity source and key
-  await this.tools.plot.createNote({
-    ...(comment.metadata?.plotNoteId
-      ? { id: comment.metadata.plotNoteId }
-      : { activity: { source: payload.itemUrl } }),
-    key: `comment-${comment.id}`,
-    content: comment.body,
-  });
+  if (comment.metadata?.plotNoteId) {
+    // Plot ID in metadata: the note originated in Plot (handles the race)
+    await this.tools.plot.updateNote({
+      id: comment.metadata.plotNoteId,
+      key: `comment-${comment.id}`,
+      content: comment.body,
+    });
+  } else {
+    // Otherwise upsert by thread source and note key
+    await this.tools.plot.createNote({
+      thread: { source: payload.itemUrl },
+      key: `comment-${comment.id}`,
+      content: comment.body,
+    });
+  }
 }
 ```
 
@@ -569,7 +586,6 @@ try {
   console.error("Operation failed:", error);
 
   await this.tools.plot.createThread({
-    type: ThreadType.Note,
     title: "Operation failed",
     notes: [
       {
@@ -583,15 +599,15 @@ try {
 ## Common Pitfalls
 
 - **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.
-- **Processing self-created threads** - Other users may change a Thread created by the twist, resulting in a callback. Be sure to check the `changes === null` and/or `thread.author.id !== this.id` to avoid re-processing.
+- **Processing self-created content** - `onNoteCreated` filters out notes created by the twist itself, but still guard against reacting to other automated actors (`note.author.type === ActorType.Twist`) to avoid loops.
 - **Always create Threads with Notes** - See "Understanding Threads and Notes" section above for the thread/message pattern and decision tree.
-- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.
-- **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
+- **Thread `type` is optional** - It's a display sub-type (`"action"`, `"notes"`, `"idea"`, `"goal"`, `"decision"`, `"discussion"`, `"announcement"`, `"ask"`). Omit it for the default; use `"action"` for tasks.
+- **Use source/key for automatic upserts (Recommended)** - Save external items as links keyed by their canonical URL/ID (connectors: `integrations.saveLink()`) for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
 - **Add Notes to existing Threads** - For source/key pattern, reference threads by source. For UUID pattern, look up stored mappings before creating new Threads. Think thread replies, not new threads.
 - Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
 - **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).
 - **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.
-- **Store auth tokens** - Don't re-request authentication unnecessarily.
+- **Don't cache auth tokens** - Fetch tokens with `this.tools.integrations.get(channelId)` when needed; the Integrations tool manages storage and refresh.
 - **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.
 - **Handle missing auth gracefully** - Check for stored auth before operations.
 - **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.

package/cli/templates/README.template.md

@@ -5,9 +5,6 @@ A Plot twist that [describe what your twist does].
 ## Quick Start
 
 ```bash
-# Install dependencies
-{{packageManager}} install
-
 # Lint your code
 {{packageManager}} lint
 
@@ -15,6 +12,8 @@ A Plot twist that [describe what your twist does].
 {{packageManager}} deploy
 ```
 
+Dependencies are installed automatically when the project is created.
+
 ## Development
 
 ### Project Structure
@@ -25,26 +24,28 @@ A Plot twist that [describe what your twist does].
 │   └── index.ts      # Main twist implementation
 ├── package.json      # twist metadata and dependencies
 ├── tsconfig.json     # TypeScript configuration
+├── AGENTS.md         # Implementation guide for AI assistants
+├── CLAUDE.md         # Claude Code entry point (includes AGENTS.md)
 └── README.md         # This file
 ```
 
 ### twist Lifecycle
 
-Your twist implements two key lifecycle methods:
+Your twist overrides lifecycle methods from the `Twist` base class:
 
-#### `activate(priority: Pick<Priority, "id">)`
+#### `activate(context?: { actor: Actor })`
 
-Called when the twist is enabled for a priority. This is where you typically:
-- Request authentication from external services
-- Create initial setup activities
+Called when the twist is installed by a user. Authentication and resource selection are handled automatically in the twist edit modal, so this is where you typically:
+- Seed initial threads
 - Initialize twist state
 
-#### `activity(activity: Activity)`
+#### `onThreadUpdated(thread, changes)` / `onNoteCreated(note, thread)`
+
+Called when a thread created by this twist is updated, or a note is added to one. Use these to:
+- Implement two-way sync with external systems
+- React to user replies and tag changes
 
-Called when an activity is routed to this twist. Use this to:
-- Process incoming activities
-- Create new activities based on external events
-- Update existing activities
+Other hooks include `upgrade()` (new version deployed) and `deactivate()` (twist uninstalled).
 
 ### Using Tools
 
@@ -61,24 +62,25 @@ build(build: ToolBuilder) {
 
 #### Built-in Tools
 
-- **Plot**: Create, update, and delete activities
+- **Plot**: Create and update threads, notes, and focuses
 - **Store**: Persist data across twist invocations
-- **Integrations**: Request OAuth authentication from external services
+- **Integrations**: OAuth authentication and channel management for external services
 - **Tasks**: Queue background tasks and batch operations
 - **Callbacks**: Create persistent function references for webhooks
 - **Network**: HTTP access permissions and webhook management
+- **AI**: LLM text generation and structured output
 
 #### Connectors
 
 External service integrations (Google Calendar, Slack, Linear, etc.) are built as Connectors. See the [Building Connectors](https://twist.plot.day/documents/Building_Connectors.html) guide.
 
-### Activity Types
+### Thread Types
 
-Plot supports three activity types:
+A thread's `type` is an optional display sub-type: `"action"`, `"notes"`, `"idea"`, `"goal"`, `"decision"`, `"discussion"`, `"announcement"`, or `"ask"`.
 
-- **ActivityType.Note**: Information without actionable requirements
-- **ActivityType.Action**: Actionable items that can be completed
-- **ActivityType.Event**: Scheduled occurrences with start/end times
+- Omit it for the default (`"notes"` in private focuses, `"discussion"` in shared ones)
+- Use `"action"` for tasks
+- Scheduled events are threads with `schedules`
 
 ### State Management
 
@@ -99,8 +101,9 @@ const token = await this.get<string>("sync_token");
 **Important**: All twist and tool functions are executed in a sandboxed, ephemeral environment with limited resources:
 
 - **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.
-- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)
-- **Use the Tasks tool**: Queue separate chunks of work with `this.run(callback)`
+- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)
+- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)
+- **Use the Tasks tool**: Queue separate chunks of work with `this.runTask(callback)` — each task runs in a new execution with a fresh request limit
 - **Break long operations**: Split large operations into smaller batches that can be processed independently
 - **Store intermediate state**: Use the Store tool to persist state between batches
 - **Examples**: Syncing large datasets, processing many API calls, or performing batch operations
@@ -115,12 +118,12 @@ async startSync(calendarId: string): Promise<void> {
     batchNumber: 1,
   });
 
-  // Queue first batch using run method
-  const callback = await this.callback("syncBatch", { calendarId });
-  await this.run(callback);
+  // Queue first batch as a task (new execution, fresh request limit)
+  const callback = await this.callback(this.syncBatch, calendarId);
+  await this.runTask(callback);
 }
 
-async syncBatch(args: any, context: { calendarId: string }): Promise<void> {
+async syncBatch(calendarId: string): Promise<void> {
   // Load state from Store
   const state = await this.get(`sync_state_${calendarId}`);
 
@@ -129,16 +132,16 @@ async syncBatch(args: any, context: { calendarId: string }): Promise<void> {
 
   if (result.hasMore) {
     // Update state and queue next batch
-    await this.set(`sync_state_${context.calendarId}`, {
+    await this.set(`sync_state_${calendarId}`, {
       nextPageToken: result.nextPageToken,
       batchNumber: state.batchNumber + 1,
     });
 
-    const nextCallback = await this.callback("syncBatch", context);
-    await this.run(nextCallback);
+    const nextCallback = await this.callback(this.syncBatch, calendarId);
+    await this.runTask(nextCallback);
   } else {
     // Cleanup when done
-    await this.clear(`sync_state_${context.calendarId}`);
+    await this.clear(`sync_state_${calendarId}`);
   }
 }
 ```
@@ -157,9 +160,9 @@ Test your twist locally before deploying:
 
 ## Resources
 
-- [Plot twist Builder Documentation](https://github.com/plotday/plot)
-- [twist Examples](https://github.com/plotday/plot/tree/main/libs/twist/examples)
-- [Tool Documentation](https://github.com/plotday/plot/tree/main/libs/twist/tools)
+- [Plot Twist Creator Documentation](https://twist.plot.day)
+- [Connector Examples](https://github.com/plotday/plot/tree/main/connectors)
+- [Tool Type Definitions](https://github.com/plotday/plot/tree/main/twister/src/tools)
 
 ## Support
 

package/dist/connector.d.ts

@@ -208,8 +208,8 @@ export type ScopeConfig = {
  *     type: "issue",
  *     label: "Issue",
  *     statuses: [
- *       { status: "open", label: "Open" },
- *       { status: "done", label: "Done" },
+ *       { status: "open", label: "Open", icon: "todo" },
+ *       { status: "done", label: "Done", icon: "done", done: true },
  *     ],
  *   }];
  *
@@ -481,17 +481,24 @@ export declare abstract class Connector<TSelf> extends Twist<TSelf> {
      */
     onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void>;
     /**
-     * Called when a user adds, removes, or changes the role of contacts on a
-     * thread owned by this connector. Override on connectors whose source
-     * supports mid-thread recipient changes (Gmail, IMAP, etc.). Connectors
-     * that can't change recipients per-message (Slack, Linear) leave this as
-     * the default no-op and should also declare
-     * `LinkTypeConfig.supportsContactChanges: false`.
-     *
-     * The dispatch fires after Plot has persisted the change. Connectors are
-     * expected to reflect it on the next outbound note (e.g. building To/Cc/Bcc
-     * headers from the current `thread.contacts` × `thread.contactMeta`) — this
-     * callback is not the right place to send a standalone notification.
+     * Called when a user changes the **thread-level sharing** of a thread owned
+     * by this connector — adding or removing a contact, or (for connectors with
+     * roles) changing a contact's role. Override on connectors whose external
+     * source can reflect that membership change, e.g. a group DM / multi-party
+     * chat (`LinkTypeConfig.sharingModel: "thread"`) or an email's To/Cc/Bcc
+     * recipients (`sharingModel: "message"`). Connectors backed by an immutable
+     * roster (most group DMs today) or by channel-level membership
+     * (`sharingModel: "channel"`) leave this as the default no-op.
+     *
+     * `role`/`from`/`to` are **null** for connectors without roles (group DMs
+     * have no roles); they carry a `contactRoles` id only for connectors that
+     * declare roles (e.g. email `to`/`cc`/`bcc`).
+     *
+     * The dispatch fires after Plot has persisted the change. A connector may
+     * reflect it actively (e.g. add/remove a participant on the external chat)
+     * or passively on the next outbound note (e.g. building To/Cc/Bcc headers
+     * from the current `thread.contacts` × `thread.contactMeta`) — this callback
+     * is not the right place to send a standalone notification.
      *
      * @param thread - The thread whose contacts changed
      * @param changes - The added/removed contacts and any role transitions on existing contacts
@@ -499,16 +506,16 @@ export declare abstract class Connector<TSelf> extends Twist<TSelf> {
     onContactsChanged(thread: Thread, changes: {
         added: Array<{
             contact: Contact;
-            role: string;
+            role: string | null;
         }>;
         removed: Array<{
             contact: Contact;
-            role: string;
+            role: string | null;
         }>;
         changed: Array<{
             contact: Contact;
-            from: string;
-            to: string;
+            from: string | null;
+            to: string | null;
         }>;
     }): Promise<void>;
     /**