@plotday/twister 0.52.0 → 0.53.0

package/src/llm-docs/twist-guide-template.ts

@@ -5,4 +5,4 @@
  * Generated from: cli/templates/AGENTS.template.md
  */
 
-export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **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.\n- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)\n- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)\n- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit\n- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count\n- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Threads and Notes\n\n**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.\n\n**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message\n3. **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.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  ├─ Has stable URL or ID?\n  │   └─ Yes → Set Thread.source to the canonical URL/ID\n  │             Create Thread (Plot handles deduplication automatically)\n  │             Use Note.key for different note types:\n  │               - \"description\" for main content\n  │               - \"metadata\" for status/priority/assignee\n  │               - \"comment-{id}\" for individual comments\n  │\n  └─ No stable identifier OR need multiple Plot threads per external item?\n      └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)\n          See SYNC_STRATEGIES.md for details\n```\n\n### Advanced Decision Tree (Strategy 3: Generate and Store IDs)\n\nOnly use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):\n\n```\nNew event/task/conversation?\n  ├─ Yes → Generate UUID with Uuid.Generate()\n  │         Create new Thread with that UUID\n  │         Store mapping: external_id → thread_uuid\n  │\n  └─ No (update/reply/comment) → Look up mapping by external_id\n      ├─ Found → Add Note to existing Thread using stored UUID\n      └─ Not found → Create new Thread with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Thread,\n  type NewThreadWithNotes,\n  type ThreadFilter,\n  type Priority,\n  type ToolBuilder,\n  Twist,\n  ThreadType,\n} from \"@plotday/twister\";\nimport { ThreadAccess, Plot } from \"@plotday/twister/tools/plot\";\n// Import your sources or tools as needed\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot, {\n        thread: { access: ThreadAccess.Create },\n      }),\n    };\n  }\n\n  async activate(_priority: Pick<Priority, \"id\">) {\n    // Auth and resource selection handled in the twist edit modal.\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled 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.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Auth and resource selection are handled in the twist edit modal.\n  // Only add custom initialization here if needed.\n}\n```\n\n**Store Parent Thread for Later (optional):**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const threadId = await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Setup complete\",\n    notes: [{\n      content: \"Your twist is ready. Threads will appear as they sync.\",\n    }],\n  });\n  await this.set(\"setup_thread_id\", threadId);\n}\n```\n\n### Event Callbacks (via build options)\n\nTwists respond to events through callbacks declared in `build()`:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {\n  const tool = this.getToolForThread(thread);\n  if (tool?.updateIssue) await tool.updateIssue(thread);\n}\n\nasync onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment. Return the external\n  // system's id + stored content so the runtime can set note.key AND\n  // record a sync baseline that preserves Plot's content on round-trip.\n  // See connectors/AGENTS.md → \"Sync baseline preservation\".\n  const comment = await externalApi.createComment(thread.meta.externalId, { body: note.content ?? \"\" });\n  if (!comment?.id) return;\n  return { key: `comment-${comment.id}`, externalContent: comment.body };\n}\n```\n\n**Respond to mentions (AI twist pattern):**\n\n```typescript\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    intents: [{\n      description: \"Respond to general questions\",\n      examples: [\"What's the weather?\", \"Help me plan my week\"],\n      handler: this.respond,\n    }],\n  },\n}),\n```\n\n**Default mention on replies:**\n\nWhen 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:\n\n- `thread.defaultMention` — Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` — Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)\n\n```typescript\n// Connector with two-way comment sync\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\n// Conversational AI twist\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    defaultMention: true,  // Follow-up notes auto-mention this twist\n    intents: [{ description: \"...\", examples: [...], handler: this.respond }],\n  },\n}),\n```\n\nWithout `defaultMention`, the twist chip appears toggled OFF by default — the user can still enable it manually per-note.\n\n## Actions\n\nActions enable user interaction:\n\n```typescript\nimport { type Action, ActionType } from \"@plotday/twister\";\n\n// External URL action\nconst urlAction: Action = {\n  title: \"Open website\",\n  type: ActionType.external,\n  url: \"https://example.com\",\n};\n\n// Callback action (uses Callbacks tool — use linkCallback, not callback)\nconst token = await this.linkCallback(this.onActionClicked, \"context\");\nconst callbackAction: Action = {\n  title: \"Click me\",\n  type: ActionType.callback,\n  callback: token,\n};\n\n// Add to thread note\nawait this.tools.plot.createThread({\n  type: ThreadType.Note,\n  title: \"Task with actions\",\n  notes: [\n    {\n      content: \"Click the actions below to take action.\",\n      actions: [urlAction, callbackAction],\n    },\n  ],\n});\n\n// Callback handler receives the Action as first argument\nasync onActionClicked(action: Action, context: string): Promise<void> {\n  // Handle action click\n}\n```\n\n## Authentication Pattern\n\nAuth 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.**\n\n```typescript\n// In your tool's build() method:\nbuild(build: ToolBuilder) {\n  return {\n    integrations: build(Integrations, {\n      providers: [{\n        provider: AuthProvider.Google,\n        scopes: [\"https://www.googleapis.com/auth/calendar\"],\n        getChannels: this.getChannels,          // List available resources after auth\n        onChannelEnabled: this.onChannelEnabled, // User enabled a resource\n        onChannelDisabled: this.onChannelDisabled, // User disabled a resource\n      }],\n    }),\n    // ...\n  };\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(AuthProvider.Google, channelId);\nif (!token) throw new Error(\"No auth token available\");\nconst client = new ApiClient({ accessToken: token.token });\n```\n\nFor per-user write-backs (e.g., RSVP, comments attributed to the acting user):\n\n```typescript\nawait this.tools.integrations.actAs(\n  AuthProvider.Google,\n  actorId,       // The user who performed the action\n  threadId,      // Thread to prompt for auth if needed\n  this.performWriteBack,\n  ...extraArgs\n);\n```\n\n## Sync Pattern\n\n### Upsert via Source/Key (Strategy 2)\n\nUse source/key for automatic upserts:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  const thread: NewThreadWithNotes = {\n    source: event.htmlLink,  // Canonical URL for automatic deduplication\n    type: ThreadType.Event,\n    title: event.summary || \"(No title)\",\n    notes: [],\n  };\n\n  if (event.description) {\n    thread.notes.push({\n      thread: { source: event.htmlLink },\n      key: \"description\",  // This key enables note-level upserts\n      content: event.description,\n    });\n  }\n\n  // Create or update — Plot handles deduplication automatically\n  await this.tools.plot.createThread(thread);\n}\n```\n\n### Advanced: Generate and Store IDs (Strategy 3)\n\nOnly use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.\n\n```typescript\nasync handleEventAdvanced(\n  incomingThread: NewThreadWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingThread.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingThreadId = await this.get<Uuid>(mappingKey);\n\n  if (existingThreadId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingThread.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        thread: { id: existingThreadId },\n        content: incomingThread.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const threadId = Uuid.Generate();\n  await this.set(mappingKey, threadId);\n\n  // Create new Thread with initial Note (new thread with first message)\n  await this.tools.plot.createThread({\n    ...incomingThread,\n    id: threadId,\n  });\n}\n```\n\n## Resource Selection\n\nResource 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.\n\n```typescript\n// In your tool:\nasync getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {\n  const client = new ApiClient({ accessToken: token.token });\n  const calendars = await client.listCalendars();\n  return calendars.map(c => ({\n    id: c.id,\n    title: c.name,\n    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),\n  }));\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.\n\n### Key Principles\n\n1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.\n2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests\n3. **Store state between batches**: Use the Store tool to persist progress\n4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)\n5. **Clean up when done**: Delete stored state after completion\n6. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n    initialSync: true,  // Track whether this is the first sync\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  // runTask creates NEW execution with fresh ~1000 request limit\n  await this.runTask(callback);\n}\n\nasync syncBatch(resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (size to stay under ~1000 request limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results using source/key pattern (automatic upserts, no manual tracking)\n  // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit\n  for (const item of result.items) {\n    // Each createThread may make ~5-10 requests depending on notes/links\n    await this.tools.plot.createThread({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: ThreadType.Note,\n      title: item.title,\n      notes: [{\n        activity: { source: item.url },\n        key: \"description\", // Use key for upsertable notes\n        content: item.description,\n      }],\n      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental\n      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n      initialSync: state.initialSync, // Preserve initialSync flag across batches\n    });\n\n    // Queue next batch - creates NEW execution with fresh request limit\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createThread({\n      type: ThreadType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Thread Sync Best Practices\n\nWhen syncing threads from external systems, follow these patterns for optimal user experience:\n\n### The `initialSync` Flag\n\nAll sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):\n\n| Field | Initial Sync | Incremental Sync | Reason |\n|-------|--------------|------------------|---------|\n| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |\n| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |\n\n**Example:**\n```typescript\nconst thread: NewThread = {\n  type: ThreadType.Event,\n  source: event.url,\n  title: event.title,\n  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental\n  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only\n};\n```\n\n**Why this matters:**\n- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved\n- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)\n\n### Two-Way Sync: Avoiding Race Conditions\n\nWhen 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.\n\n**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.\n\n```typescript\nasync pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {\n  // Create external item with Plot ID in metadata for webhook correlation\n  const externalComment = await externalApi.createComment(externalItemId, {\n    body: note.content,\n    metadata: { plotNoteId: note.id },\n  });\n\n  // Update Note with external key AFTER creation\n  // A webhook may arrive before this completes — that's OK (see onWebhook below)\n  await this.tools.plot.updateNote({\n    id: note.id,\n    key: `comment-${externalComment.id}`,\n  });\n}\n\nasync onWebhook(payload: WebhookPayload): Promise<void> {\n  const comment = payload.comment;\n\n  // Use Plot ID from metadata if present (handles race condition),\n  // otherwise fall back to upserting by activity source and key\n  await this.tools.plot.createNote({\n    ...(comment.metadata?.plotNoteId\n      ? { id: comment.metadata.plotNoteId }\n      : { activity: { source: payload.itemUrl } }),\n    key: `comment-${comment.id}`,\n    content: comment.body,\n  });\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **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.\n- **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.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.\n- **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).\n- **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.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **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).\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n- **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.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **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.\n- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)\n- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)\n- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit\n- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count\n- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Threads and Notes\n\n**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.\n\n**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message\n3. **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.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  ├─ Has stable URL or ID?\n  │   └─ Yes → Set Thread.source to the canonical URL/ID\n  │             Create Thread (Plot handles deduplication automatically)\n  │             Use Note.key for different note types:\n  │               - \"description\" for main content\n  │               - \"metadata\" for status/priority/assignee\n  │               - \"comment-{id}\" for individual comments\n  │\n  └─ No stable identifier OR need multiple Plot threads per external item?\n      └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)\n          See SYNC_STRATEGIES.md for details\n```\n\n### Advanced Decision Tree (Strategy 3: Generate and Store IDs)\n\nOnly use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):\n\n```\nNew event/task/conversation?\n  ├─ Yes → Generate UUID with Uuid.Generate()\n  │         Create new Thread with that UUID\n  │         Store mapping: external_id → thread_uuid\n  │\n  └─ No (update/reply/comment) → Look up mapping by external_id\n      ├─ Found → Add Note to existing Thread using stored UUID\n      └─ Not found → Create new Thread with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Thread,\n  type NewThreadWithNotes,\n  type ThreadFilter,\n  type Priority,\n  type ToolBuilder,\n  Twist,\n  ThreadType,\n} from \"@plotday/twister\";\nimport { ThreadAccess, Plot } from \"@plotday/twister/tools/plot\";\n// Import your sources or tools as needed\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot, {\n        thread: { access: ThreadAccess.Create },\n      }),\n    };\n  }\n\n  async activate(_priority: Pick<Priority, \"id\">) {\n    // Auth and resource selection handled in the twist edit modal.\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled 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.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Auth and resource selection are handled in the twist edit modal.\n  // Only add custom initialization here if needed.\n}\n```\n\n**Store Parent Thread for Later (optional):**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const threadId = await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Setup complete\",\n    notes: [{\n      content: \"Your twist is ready. Threads will appear as they sync.\",\n    }],\n  });\n  await this.set(\"setup_thread_id\", threadId);\n}\n```\n\n### Event Callbacks (via build options)\n\nTwists respond to events through callbacks declared in `build()`:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {\n  const tool = this.getToolForThread(thread);\n  if (tool?.updateIssue) await tool.updateIssue(thread);\n}\n\nasync onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment. Return the external\n  // system's id + stored content so the runtime can set note.key AND\n  // record a sync baseline that preserves Plot's content on round-trip.\n  // See connectors/AGENTS.md → \"Sync baseline preservation\".\n  const comment = await externalApi.createComment(thread.meta.externalId, { body: note.content ?? \"\" });\n  if (!comment?.id) return;\n  return { key: `comment-${comment.id}`, externalContent: comment.body };\n}\n```\n\n**Respond to mentions (AI twist pattern):**\n\n```typescript\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    intents: [{\n      description: \"Respond to general questions\",\n      examples: [\"What's the weather?\", \"Help me plan my week\"],\n      handler: this.respond,\n    }],\n  },\n}),\n```\n\n**Default mention on replies:**\n\nWhen 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:\n\n- `thread.defaultMention` — Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` — Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)\n\n```typescript\n// Connector with two-way comment sync\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\n// Conversational AI twist\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    defaultMention: true,  // Follow-up notes auto-mention this twist\n    intents: [{ description: \"...\", examples: [...], handler: this.respond }],\n  },\n}),\n```\n\nWithout `defaultMention`, the twist chip appears toggled OFF by default — the user can still enable it manually per-note.\n\n## Actions\n\nActions enable user interaction:\n\n```typescript\nimport { type Action, ActionType } from \"@plotday/twister\";\n\n// External URL action\nconst urlAction: Action = {\n  title: \"Open website\",\n  type: ActionType.external,\n  url: \"https://example.com\",\n};\n\n// Callback action (uses Callbacks tool — use linkCallback, not callback)\nconst token = await this.linkCallback(this.onActionClicked, \"context\");\nconst callbackAction: Action = {\n  title: \"Click me\",\n  type: ActionType.callback,\n  callback: token,\n};\n\n// Add to thread note\nawait this.tools.plot.createThread({\n  type: ThreadType.Note,\n  title: \"Task with actions\",\n  notes: [\n    {\n      content: \"Click the actions below to take action.\",\n      actions: [urlAction, callbackAction],\n    },\n  ],\n});\n\n// Callback handler receives the Action as first argument\nasync onActionClicked(action: Action, context: string): Promise<void> {\n  // Handle action click\n}\n```\n\n## Authentication Pattern\n\nAuth 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.**\n\n```typescript\n// In your tool's build() method:\nbuild(build: ToolBuilder) {\n  return {\n    integrations: build(Integrations, {\n      providers: [{\n        provider: AuthProvider.Google,\n        scopes: [\"https://www.googleapis.com/auth/calendar\"],\n        getChannels: this.getChannels,          // List available resources after auth\n        onChannelEnabled: this.onChannelEnabled, // User enabled a resource\n        onChannelDisabled: this.onChannelDisabled, // User disabled a resource\n      }],\n    }),\n    // ...\n  };\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(AuthProvider.Google, channelId);\nif (!token) throw new Error(\"No auth token available\");\nconst client = new ApiClient({ accessToken: token.token });\n```\n\nFor per-user write-backs (e.g., RSVP, comments attributed to the acting user):\nthe dispatch runtime routes the change to the acting user's own connector\ninstance, so your callback (`onScheduleContactUpdated`, etc.) already runs\nunder that user's auth. Just call `this.tools.integrations.get(channelId)`\nto fetch the token and the write-back is attributed correctly. If the\nacting user has no connection of this type, the change lives in Plot but\nis not dispatched.\n\n## Sync Pattern\n\n### Upsert via Source/Key (Strategy 2)\n\nUse source/key for automatic upserts:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  const thread: NewThreadWithNotes = {\n    source: event.htmlLink,  // Canonical URL for automatic deduplication\n    type: ThreadType.Event,\n    title: event.summary || \"(No title)\",\n    notes: [],\n  };\n\n  if (event.description) {\n    thread.notes.push({\n      thread: { source: event.htmlLink },\n      key: \"description\",  // This key enables note-level upserts\n      content: event.description,\n    });\n  }\n\n  // Create or update — Plot handles deduplication automatically\n  await this.tools.plot.createThread(thread);\n}\n```\n\n### Advanced: Generate and Store IDs (Strategy 3)\n\nOnly use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.\n\n```typescript\nasync handleEventAdvanced(\n  incomingThread: NewThreadWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingThread.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingThreadId = await this.get<Uuid>(mappingKey);\n\n  if (existingThreadId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingThread.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        thread: { id: existingThreadId },\n        content: incomingThread.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const threadId = Uuid.Generate();\n  await this.set(mappingKey, threadId);\n\n  // Create new Thread with initial Note (new thread with first message)\n  await this.tools.plot.createThread({\n    ...incomingThread,\n    id: threadId,\n  });\n}\n```\n\n## Resource Selection\n\nResource 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.\n\n```typescript\n// In your tool:\nasync getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {\n  const client = new ApiClient({ accessToken: token.token });\n  const calendars = await client.listCalendars();\n  return calendars.map(c => ({\n    id: c.id,\n    title: c.name,\n    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),\n  }));\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.\n\n### Key Principles\n\n1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.\n2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests\n3. **Store state between batches**: Use the Store tool to persist progress\n4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)\n5. **Clean up when done**: Delete stored state after completion\n6. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n    initialSync: true,  // Track whether this is the first sync\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  // runTask creates NEW execution with fresh ~1000 request limit\n  await this.runTask(callback);\n}\n\nasync syncBatch(resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (size to stay under ~1000 request limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results using source/key pattern (automatic upserts, no manual tracking)\n  // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit\n  for (const item of result.items) {\n    // Each createThread may make ~5-10 requests depending on notes/links\n    await this.tools.plot.createThread({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: ThreadType.Note,\n      title: item.title,\n      notes: [{\n        activity: { source: item.url },\n        key: \"description\", // Use key for upsertable notes\n        content: item.description,\n      }],\n      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental\n      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n      initialSync: state.initialSync, // Preserve initialSync flag across batches\n    });\n\n    // Queue next batch - creates NEW execution with fresh request limit\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createThread({\n      type: ThreadType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Thread Sync Best Practices\n\nWhen syncing threads from external systems, follow these patterns for optimal user experience:\n\n### The `initialSync` Flag\n\nAll sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):\n\n| Field | Initial Sync | Incremental Sync | Reason |\n|-------|--------------|------------------|---------|\n| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |\n| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |\n\n**Example:**\n```typescript\nconst thread: NewThread = {\n  type: ThreadType.Event,\n  source: event.url,\n  title: event.title,\n  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental\n  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only\n};\n```\n\n**Why this matters:**\n- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved\n- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)\n\n### Two-Way Sync: Avoiding Race Conditions\n\nWhen 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.\n\n**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.\n\n```typescript\nasync pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {\n  // Create external item with Plot ID in metadata for webhook correlation\n  const externalComment = await externalApi.createComment(externalItemId, {\n    body: note.content,\n    metadata: { plotNoteId: note.id },\n  });\n\n  // Update Note with external key AFTER creation\n  // A webhook may arrive before this completes — that's OK (see onWebhook below)\n  await this.tools.plot.updateNote({\n    id: note.id,\n    key: `comment-${externalComment.id}`,\n  });\n}\n\nasync onWebhook(payload: WebhookPayload): Promise<void> {\n  const comment = payload.comment;\n\n  // Use Plot ID from metadata if present (handles race condition),\n  // otherwise fall back to upserting by activity source and key\n  await this.tools.plot.createNote({\n    ...(comment.metadata?.plotNoteId\n      ? { id: comment.metadata.plotNoteId }\n      : { activity: { source: payload.itemUrl } }),\n    key: `comment-${comment.id}`,\n    content: comment.body,\n  });\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **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.\n- **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.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.\n- **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).\n- **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.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **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).\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n- **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.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";

package/src/plot.ts

@@ -1,7 +1,6 @@
 import type { NewSchedule, NewScheduleOccurrence, Schedule } from "./schedule";
 import { type Tag } from "./tag";
 import { type Callback } from "./tools/callbacks";
-import { type AuthProvider } from "./tools/integrations";
 import { type JSONValue } from "./utils/types";
 import { Uuid } from "./utils/uuid";
 
@@ -184,6 +183,8 @@ export enum ActionType {
   conferencing = "conferencing",
   /** File attachment links stored in R2 */
   file = "file",
+  /** Reference to an attachment hosted by a connector's source system */
+  fileRef = "fileRef",
   /** Thread reference links for navigating to related threads */
   thread = "thread",
   /** Structured plan of operations for user approval */
@@ -301,6 +302,22 @@ export type Action =
       /** Intrinsic height of the image in pixels (only for image files) */
       imageHeight?: number | null;
     }
+  | {
+      /** Reference to an attachment hosted by a connector's source system */
+      type: ActionType.fileRef;
+      /** Opaque identifier interpreted only by the owning connector */
+      ref: string;
+      /** Display filename */
+      fileName: string;
+      /** File size in bytes if known */
+      fileSize: number | null;
+      /** MIME type */
+      mimeType: string;
+      /** Intrinsic width of the image in pixels (only for image files) */
+      imageWidth?: number | null;
+      /** Intrinsic height of the image in pixels (only for image files) */
+      imageHeight?: number | null;
+    }
   | {
       /** Thread reference action for navigating to a related thread */
       type: ActionType.thread;
@@ -382,6 +399,35 @@ export type Tags = { [K in Tag]?: ActorId[] };
  */
 export type NewTags = { [K in Tag]?: NewActor[] };
 
+/**
+ * A single emoji reaction key. Either:
+ * - A Unicode emoji grapheme cluster (e.g. `"👍"`, `"👨‍👩‍👧"`), or
+ * - A provider-scoped custom-emoji ref of the form
+ *   `"<provider>:<workspaceId>/<name>"` (e.g. `"slack:T0123/party_parrot"`).
+ *
+ * Anything matching a known provider prefix is treated as a custom-emoji
+ * reference; everything else is rendered as the Unicode it contains.
+ *
+ * Reactions are the open-set counterpart to {@link Tag}'s count range
+ * (`1000+`). Use reactions for emoji that round-trip with chat platforms;
+ * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,
+ * ...).
+ */
+export type Reaction = string;
+
+/**
+ * Emoji reactions on an item, keyed by emoji string, with the list of
+ * actors who added each reaction.
+ */
+export type Reactions = Record<Reaction, ActorId[]>;
+
+/**
+ * A set of reactions to add to an item, along with the actors adding each
+ * reaction. To remove a reaction for a given actor, omit them from the
+ * `NewActor[]` list — passing an empty list removes the reaction entirely.
+ */
+export type NewReactions = Record<Reaction, NewActor[]>;
+
 /**
  * Thread access level determining visibility.
  * - "public": Visible to all users with priority access
@@ -408,6 +454,12 @@ export type ThreadCommon = {
   archived: boolean;
   /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */
   tags: Tags;
+  /**
+   * Emoji reactions on this item. Maps each emoji (Unicode grapheme or
+   * `provider:workspace/name` custom-emoji ref) to the list of actor IDs
+   * who reacted with it.
+   */
+  reactions: Reactions;
 };
 
 /**
@@ -454,7 +506,7 @@ export type NewThreadWithNotes = NewThread & {
  * ```
  */
 export type NewThread = Partial<
-  Omit<ThreadFields, "priority" | "tags" | "id" | "accessContacts">
+  Omit<ThreadFields, "priority" | "tags" | "reactions" | "id" | "accessContacts">
 > &
   (
     | {
@@ -474,6 +526,12 @@ export type NewThread = Partial<
      */
     tags?: NewTags;
 
+    /**
+     * Emoji reactions to set on the new thread.
+     * Each emoji maps to the list of actors who reacted with it.
+     */
+    reactions?: NewReactions;
+
     /**
      * The thread's sub-type/category. Sets the thread's icon.
      * If omitted, defaults to "notes" (private) or "discussion" (shared).
@@ -549,6 +607,12 @@ type ThreadSingleUpdateFields = ThreadBulkUpdateFields & {
    */
   tags?: NewTags;
 
+  /**
+   * Emoji reactions to change on the thread. Pass an empty `NewActor[]` to
+   * remove a reaction entirely; omit an emoji to leave it untouched.
+   */
+  reactions?: NewReactions;
+
   /**
    * Add or remove the twist's tags.
    * Maps tag ID to boolean: true = add tag, false = remove tag.
@@ -651,7 +715,7 @@ export type Note = ThreadCommon & {
 export type NewNote = Partial<
   Omit<
     Note,
-    "author" | "thread" | "tags" | "mentions" | "accessContacts" | "id" | "key" | "reNote"
+    "author" | "thread" | "tags" | "reactions" | "mentions" | "accessContacts" | "id" | "key" | "reNote"
   >
 > &
   ({ id: Uuid } | { key: string } | {}) & {
@@ -681,6 +745,12 @@ export type NewNote = Partial<
      */
     tags?: NewTags;
 
+    /**
+     * Emoji reactions to set on the note. Pass an empty `NewActor[]` to
+     * remove a reaction entirely; omit an emoji to leave it untouched.
+     */
+    reactions?: NewReactions;
+
     /**
      * Contacts who can see this note, or null/undefined to inherit thread visibility.
      * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).
@@ -748,6 +818,12 @@ export type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &
      */
     tags?: NewTags;
 
+    /**
+     * Emoji reactions to change on the note. Pass an empty `NewActor[]` to
+     * remove a reaction entirely; omit an emoji to leave it untouched.
+     */
+    reactions?: NewReactions;
+
     /**
      * Add or remove the twist's tags.
      * Maps tag ID to boolean: true = add tag, false = remove tag.
@@ -861,8 +937,22 @@ type NewContactBase = {
   /**
    * External provider account source. Used for identity resolution
    * when email is unavailable and for privacy compliance reporting.
+   *
+   * The runtime scopes the resulting `contact_external_account` row to
+   * the dispatching twist instance (i.e. one row per connection per
+   * contact), so the same Plot contact can have multiple rows when
+   * reachable through multiple connections (e.g. two Slack workspaces,
+   * Gmail + Google Chat sharing one Google account).
+   */
+  source?: { accountId: string };
+  /**
+   * Optional connector-defined role for this contact on the thread, matching
+   * a `LinkTypeConfig.contactRoles[].id` (e.g. "to" / "cc" / "bcc" for
+   * email, "required" / "optional" for calendar). Omitted ⇒ default role.
+   * Connectors set this on inbound sync; the runtime persists it under
+   * `thread.contact_meta[contact_id].role`.
    */
-  source?: { provider: AuthProvider; accountId: string };
+  role?: string;
 };
 
 /**

package/src/tag.ts

@@ -1,54 +1,23 @@
 /**
- * Thread tags. Three types:
- * 1. Special tags, which trigger other behaviors
- * 2. Toggle tags, which anyone can toggle a shared value on or off
- * 3. Count tags, where everyone can add or remove their own
+ * Compute tags — system state the runtime auto-manages on threads and
+ * notes (`todo`, `done`, `twist` activity marker, …).
+ *
+ * The toggle range (100–999) and count range (1000–1027) have been
+ * retired in favour of the open Unicode emoji `Reaction` type — see
+ * `@plotday/twister/plot`'s `Reactions` / `NewReactions` and the
+ * per-row `note.reactions` / `thread.reactions` fields. Connectors
+ * route emoji reactions through `reactions`, not `tags`.
+ *
+ * `Tag.Twist` is the surviving non-trivial tag: a system marker the
+ * runtime adds to a note while a twist is processing it, and clears
+ * once the twist returns. It's not user-facing and not a reaction.
  */
 export enum Tag {
-  // Special tags
   Todo = 1,
   Done = 3,
-
-  // Toggle tags
-  Pinned = 100,
-  Urgent = 101,
-  Goal = 103,
-  Decision = 104,
-  Waiting = 105,
-  Blocked = 106,
-  Warning = 107,
-  Question = 108,
-  Twist = 109,
-  Star = 110,
-  Idea = 111,
-
-  // Count tags
-  Yes = 1000,
-  No = 1001,
-  Volunteer = 1002,
-  Tada = 1003,
-  Fire = 1004,
-  Totally = 1005,
-  Looking = 1006,
-  Love = 1007,
-  Rocket = 1008,
-  Sparkles = 1009,
-  Thanks = 1010,
-  Smile = 1011,
-  Wave = 1012,
-  Praise = 1015,
-  Applause = 1016,
-  Cool = 1017,
-  Sad = 1018,
-  Reply = 1019,
-  Thinking = 1013,
-  Remember = 1014,
-  Agreed = 1020,
-  Relieved = 1021,
-  Send = 1022,
-  Noted = 1023,
-  Laugh = 1024,
-  Surprised = 1025,
-  Confused = 1026,
-  Dismayed = 1027,
+  /** System marker for "a twist is processing this note." Set by the
+   * runtime when a twist callback fires, cleared on return. Twists
+   * may still write `{ [Tag.Twist]: true | false }` to twistTags to
+   * mark/unmark a note explicitly. */
+  Twist = 12,
 }

package/src/tools/files.ts

@@ -0,0 +1,37 @@
+import { ITool } from "..";
+
+/**
+ * Built-in tool for reading files attached to notes in Plot.
+ *
+ * Files are uploaded by clients via POST /files which creates an
+ * ActionType.file entry on a note. Connectors call read() during outbound
+ * (e.g. onNoteCreated) to retrieve those bytes and send them to the source
+ * system.
+ *
+ * For inbound attachments, connectors emit ActionType.fileRef actions and
+ * implement Connector.downloadAttachment — no upload tool is needed because
+ * inbound bytes never enter Plot's R2 storage.
+ */
+export abstract class Files extends ITool {
+  /**
+   * Read a file uploaded by a client and attached to a note in a priority
+   * where this twist is installed.
+   *
+   * @param fileId The id from an ActionType.file action.
+   * @returns Bytes plus original metadata.
+   * @throws FileNotFoundError if the file is missing or out of scope.
+   */
+  abstract read(fileId: string): Promise<{
+    data: Uint8Array;
+    fileName: string;
+    mimeType: string;
+    fileSize: number;
+  }>;
+}
+
+export class FileNotFoundError extends Error {
+  constructor(fileId: string) {
+    super(`File not found or out of scope: ${fileId}`);
+    this.name = "FileNotFoundError";
+  }
+}

package/src/tools/index.ts

@@ -1,6 +1,7 @@
 export * from "./twists";
 export * from "./ai";
 export * from "./callbacks";
+export * from "./files";
 export * from "./integrations";
 export * from "./network";
 export * from "./plot";

package/src/tools/integrations.ts

@@ -4,9 +4,7 @@ import {
   type NewContact,
   type NewLinkWithNotes,
   ITool,
-  Serializable,
 } from "..";
-import { Tag } from "../tag";
 import type { JSONValue } from "../utils/types";
 import type { Uuid } from "../utils/uuid";
 
@@ -34,6 +32,13 @@ export type LinkTypeConfig = {
   type: string;
   /** Human-readable label (e.g., "Issue", "Pull Request") */
   label: string;
+  /**
+   * Connector's word for a note on a linked item of this type — used by the
+   * Flutter app to adapt note/composer copy ("Add a comment" on Linear,
+   * "Add a message" on Slack, "Add a reply" on Gmail). Defaults to "note"
+   * when omitted. Use the singular noun in title case (e.g. "Comment").
+   */
+  noteLabel?: string;
   /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */
   logo?: string;
   /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */
@@ -46,8 +51,6 @@ export type LinkTypeConfig = {
     status: string;
     /** Human-readable label (e.g., "Open", "Done") */
     label: string;
-    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */
-    tag?: Tag;
     /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */
     done?: boolean;
     /**
@@ -82,18 +85,121 @@ export type LinkTypeConfig = {
      * Gmail's "starred", Linear's "todo").
      */
     todo?: boolean;
-    /**
-     * Default status applied when Plot asks the connector to create a new
-     * item of this type via `Connector.onCreateLink`. Declaring at least one
-     * status with `createDefault: true` is how a link type opts in to
-     * Plot-initiated creation. At most one status per type should set this.
-     */
-    createDefault?: boolean;
   }>;
   /** Whether this link type supports displaying and changing the assignee */
   supportsAssignee?: boolean;
   /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */
   defaultCreateThreads?: string;
+  /**
+   * Opt-in: declares this link type is composable from Plot via
+   * `Connector.onCreateLink`. Omit to make the link type sync-only (no
+   * "Create new …" picker entry).
+   *
+   * Connectors that need multiple compose modes for what users perceive as
+   * the same kind of thing (e.g. Slack channel post vs DM) should declare
+   * **separate linkTypes**, one per user-facing thread type. That keeps
+   * each linkType isomorphic to one filter chip.
+   */
+  compose?: ComposeConfig;
+  /**
+   * Per-connector contact roles. Examples:
+   *   email   → [{id:"to",label:"To",default:true},{id:"cc",label:"CC"},{id:"bcc",label:"BCC",hidden:true}]
+   *   calendar → [{id:"required",label:"Required",default:true},{id:"optional",label:"Optional"}]
+   *
+   * Plot uses this list to render a role picker on each contact chip in the
+   * composer and to label non-default roles on existing threads. Exactly one
+   * role should be marked `default: true`. Connectors that don't distinguish
+   * roles (Slack, Linear) omit this field entirely.
+   */
+  contactRoles?: ContactRoleConfig[];
+  /**
+   * Whether contacts on an existing thread can be added, removed, or have
+   * their role changed (email-style mid-thread recipient changes). When
+   * false, the thread's contact list is fixed after creation. Defaults to
+   * false when omitted.
+   */
+  supportsContactChanges?: boolean;
+  /**
+   * Declares how sharing on threads of this link type is scoped:
+   *
+   * - `"thread"` (default): one roster shared across all notes in the
+   *   thread. Native Plot threads, Slack DMs, calendar events.
+   * - `"channel"`: visibility is the external channel's membership;
+   *   the per-thread `contacts` array is ignored for sharing UI.
+   *   Slack channels, Linear projects.
+   * - `"message"`: each note carries its own recipient set via
+   *   `note.access_contacts`; the thread roster is the union across
+   *   all messages. Email.
+   *
+   * Omit to default to `"thread"`. When set to `"message"`, every
+   * note this connector ingests must populate `access_contacts`
+   * explicitly (never NULL).
+   */
+  sharingModel?: "thread" | "channel" | "message";
+};
+
+/**
+ * Declares how a link type is composable from Plot via
+ * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.
+ */
+export type ComposeConfig = {
+  /**
+   * Selects the destination model for the "Create new …" picker.
+   *
+   * - `"channels"` (default): one chip per enabled channel (e.g. a Linear
+   *   team, a Slack channel). Existing behaviour for task-tracker / calendar
+   *   connectors.
+   * - `"contacts"`: one chip per connection (account); the user picks
+   *   recipients from their contacts. The runtime pre-resolves the chosen
+   *   Plot contacts to platform account IDs via the per-connection
+   *   `contact_external_account` rows and delivers them as
+   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific
+   *   connection are filtered out of the picker — used by closed-roster
+   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).
+   * - `"addresses"`: one chip per connection; the picker accepts any
+   *   contact with an addressable identifier (e.g. an email) or a free-form
+   *   typed address. The runtime fills `recipients` for contacts with a
+   *   connection-scoped row and falls back to the contact's primary address
+   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive
+   *   via the thread's `inviteEmails`. Used by open address spaces like
+   *   Gmail.
+   */
+  targets?: "channels" | "contacts" | "addresses";
+  /**
+   * Status to assign newly-created links. Should match an entry in the
+   * parent linkType's `statuses[]`, OR a symbolic id that the connector's
+   * `onCreateLink` resolves itself (e.g. Linear's `"unstarted"` category is
+   * resolved per-team to a state UUID inside the connector — see
+   * `connectors/linear/src/linear.ts`).
+   */
+  status: string;
+  /**
+   * Optional override for the picker chip / "Create new …" copy. Defaults
+   * to the parent linkType's `label`. Use to disambiguate compose entries
+   * when the parent label alone isn't specific enough (e.g. "Direct
+   * messages" for a DM-mode compose on a chat connector).
+   */
+  label?: string;
+};
+
+/**
+ * Declares one contact role for a connector's link type. See
+ * `LinkTypeConfig.contactRoles`.
+ */
+export type ContactRoleConfig = {
+  /** Stable machine id, e.g. "to" / "cc" / "bcc" / "required" / "optional". */
+  id: string;
+  /** Display label shown next to a contact chip, e.g. "To", "CC", "Required". */
+  label: string;
+  /** Exactly one role per linkType should be marked default. */
+  default?: boolean;
+  /**
+   * Hidden roles are visible only to (a) the contact themselves and
+   * (b) the user who added them. The API filters them out of every other
+   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style
+   * semantics where other recipients must not see the hidden contact.
+   */
+  hidden?: boolean;
 };
 
 /**
@@ -209,31 +315,6 @@ export abstract class Integrations extends ITool {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;
 
-  /**
-   * Execute a callback as a specific actor, requesting auth if needed.
-   *
-   * If the actor has a valid token, calls the callback immediately with it.
-   * If the actor has no token, creates a private auth note in the specified
-   * activity prompting them to connect. Once they authorize, this callback fires.
-   *
-   * @param provider - The OAuth provider
-   * @param actorId - The actor to act as
-   * @param activityId - The activity to create an auth note in (if needed)
-   * @param callback - Function to call with the token
-   * @param extraArgs - Additional arguments to pass to the callback
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  abstract actAs<
-    TArgs extends Serializable[],
-    TCallback extends (token: AuthToken, ...args: TArgs) => any
-  >(
-    provider: AuthProvider,
-    actorId: ActorId,
-    activityId: Uuid,
-    callback: TCallback,
-    ...extraArgs: TArgs
-  ): Promise<void>;
-
   /**
    * Saves a link with notes to the connector's priority.
    *
@@ -274,10 +355,15 @@ export abstract class Integrations extends ITool {
   abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;
 
   /**
-   * Saves contacts to the connector's priority.
+   * Upserts contacts into the connector's priority without requiring a Link.
+   *
+   * Use this for messaging connectors to bulk-sync workspace members so the
+   * recipient picker can filter contacts by reachable platform account. Populate
+   * `NewContact.source` to persist `contact_external_account` rows (the platform
+   * identity used to address the contact). Returns one `Actor` per input, in order.
    *
-   * @param contacts - Array of contacts to save
-   * @returns Promise resolving to the saved actors
+   * @param contacts - Contacts to upsert, keyed by `source`/`key`
+   * @returns Promise resolving to the saved actors, 1:1 with input order
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;