@plotday/twister 0.56.0 → 0.58.0

package/dist/tools/tasks.d.ts

@@ -29,18 +29,18 @@ import type { Callback } from "./callbacks";
  *
  * @example
  * ```typescript
- * class SyncTool extends Tool {
+ * class SyncTool extends Tool<SyncTool> {
  *   async startBatchSync(totalItems: number) {
  *     // Store initial state using built-in set method
  *     await this.set("sync_progress", { processed: 0, total: totalItems });
  *
  *     // Create callback and queue first batch
- *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     const callback = await this.callback(this.processBatch, 1);
  *     // runTask creates NEW execution with fresh ~1000 request limit
  *     await this.runTask(callback);
  *   }
  *
- *   async processBatch(args: any, context: { batchNumber: number }) {
+ *   async processBatch(batchNumber: number) {
  *     // Process one batch of items (sized to stay under request limit)
  *     const progress = await this.get("sync_progress");
  *
@@ -60,9 +60,7 @@ import type { Callback } from "./callbacks";
  *
  *     if (progress.processed < progress.total) {
  *       // Queue next batch - creates NEW execution with fresh request limit
- *       const callback = await this.callback("processBatch", {
- *         batchNumber: context.batchNumber + 1
- *       });
+ *       const callback = await this.callback(this.processBatch, batchNumber + 1);
  *       await this.runTask(callback);
  *     }
  *   }
@@ -71,7 +69,7 @@ import type { Callback } from "./callbacks";
  *     const tomorrow = new Date();
  *     tomorrow.setDate(tomorrow.getDate() + 1);
  *
- *     const callback = await this.callback("cleanupOldData");
+ *     const callback = await this.callback(this.cleanupOldData);
  *     // Schedule for future execution
  *     return await this.runTask(callback, { runAt: tomorrow });
  *   }
@@ -102,7 +100,7 @@ export declare abstract class Tasks extends ITool {
      * @example
      * ```typescript
      * // Break large loop into batches to stay under request limit
-     * const callback = await this.callback("syncBatch", { page: 1 });
+     * const callback = await this.callback(this.syncBatch, 1);
      * await this.runTask(callback); // Fresh execution with ~1000 requests
      * ```
      */

package/dist/tools/tasks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,8BAAsB,KAAM,SAAQ,KAAK;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IAEH,QAAQ,CAAC,OAAO,CACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAA;KAAE,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;;OAQG;IAEH,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjD;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CACzC"}
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,8BAAsB,KAAM,SAAQ,KAAK;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IAEH,QAAQ,CAAC,OAAO,CACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAA;KAAE,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;;OAQG;IAEH,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjD;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CACzC"}

package/dist/tools/tasks.js

@@ -28,18 +28,18 @@ import { ITool } from "..";
  *
  * @example
  * ```typescript
- * class SyncTool extends Tool {
+ * class SyncTool extends Tool<SyncTool> {
  *   async startBatchSync(totalItems: number) {
  *     // Store initial state using built-in set method
  *     await this.set("sync_progress", { processed: 0, total: totalItems });
  *
  *     // Create callback and queue first batch
- *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     const callback = await this.callback(this.processBatch, 1);
  *     // runTask creates NEW execution with fresh ~1000 request limit
  *     await this.runTask(callback);
  *   }
  *
- *   async processBatch(args: any, context: { batchNumber: number }) {
+ *   async processBatch(batchNumber: number) {
  *     // Process one batch of items (sized to stay under request limit)
  *     const progress = await this.get("sync_progress");
  *
@@ -59,9 +59,7 @@ import { ITool } from "..";
  *
  *     if (progress.processed < progress.total) {
  *       // Queue next batch - creates NEW execution with fresh request limit
- *       const callback = await this.callback("processBatch", {
- *         batchNumber: context.batchNumber + 1
- *       });
+ *       const callback = await this.callback(this.processBatch, batchNumber + 1);
  *       await this.runTask(callback);
  *     }
  *   }
@@ -70,7 +68,7 @@ import { ITool } from "..";
  *     const tomorrow = new Date();
  *     tomorrow.setDate(tomorrow.getDate() + 1);
  *
- *     const callback = await this.callback("cleanupOldData");
+ *     const callback = await this.callback(this.cleanupOldData);
  *     // Schedule for future execution
  *     return await this.runTask(callback, { runAt: tomorrow });
  *   }

package/dist/tools/tasks.js.map

@@ -1 +1 @@
-{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAG3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,MAAM,OAAgB,KAAM,SAAQ,KAAK;CAuDxC"}
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAG3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAM,OAAgB,KAAM,SAAQ,KAAK;CAuDxC"}

package/dist/tools/twists.d.ts

@@ -56,10 +56,10 @@ export type TwistPermissions = Record<string, Record<string, string[]>>;
  *
  * @example
  * ```typescript
- * class TwistBuilderTwist extends Twist {
+ * class TwistBuilderTwist extends Twist<TwistBuilderTwist> {
  *   build(build: ToolBuilder) {
  *    return {
- *      twists: build.get(Twists)
+ *      twists: build(Twists)
  *    }
  *   }
  *
@@ -72,14 +72,15 @@ export type TwistPermissions = Record<string, Record<string, string[]>>;
  */
 export declare abstract class Twists extends ITool {
     /**
-     * Creates a new twist ID and grants access to people in the current focus.
+     * Creates a new twist package ID. Ownership of the ID is claimed lazily
+     * on first deploy — no upfront registration happens beyond generating it.
      *
      * @returns Promise resolving to the generated twist ID
      * @throws When twist creation fails
      *
      * @example
      * ```typescript
-     * const twistId = await twist.create();
+     * const twistId = await this.tools.twists.create();
      * console.log(`Your twist ID: ${twistId}`);
      * ```
      */
@@ -97,15 +98,15 @@ export declare abstract class Twists extends ITool {
      *
      * @example
      * ```typescript
-     * const source = await twist.generate(`
+     * const source = await this.tools.twists.generate(`
      * # Calendar Sync Twist
      *
-     * This twist syncs Google Calendar events to Plot activities.
+     * This twist syncs Google Calendar events to Plot threads.
      *
      * ## Features
      * - Authenticate with Google
      * - Sync calendar events
-     * - Create activities from events
+     * - Create threads from events
      * `);
      *
      * // source.dependencies: { "@plotday/twister": "workspace:^", ... }
@@ -135,7 +136,7 @@ export declare abstract class Twists extends ITool {
      * @example
      * ```typescript
      * // Deploy with a module
-     * const result = await twist.deploy({
+     * const result = await this.tools.twists.deploy({
      *   twistId: 'abc-123-...',
      *   module: 'export default class MyTwist extends Twist {...}',
      *   environment: 'personal',
@@ -145,8 +146,8 @@ export declare abstract class Twists extends ITool {
      * console.log(`Deployed version ${result.version}`);
      *
      * // Deploy with source
-     * const source = await twist.generate(spec);
-     * const result = await twist.deploy({
+     * const source = await this.tools.twists.generate(spec);
+     * const result = await this.tools.twists.deploy({
      *   twistId: 'abc-123-...',
      *   source,
      *   environment: 'personal',
@@ -154,7 +155,7 @@ export declare abstract class Twists extends ITool {
      * });
      *
      * // Validate with dryRun
-     * const result = await twist.deploy({
+     * const result = await this.tools.twists.deploy({
      *   twistId: 'abc-123-...',
      *   source,
      *   dryRun: true,
@@ -194,11 +195,11 @@ export declare abstract class Twists extends ITool {
      * @example
      * ```typescript
      * // Create twist and callback
-     * const twistId = await this.twist.create();
-     * const callback = await this.callback.create("onLogs");
+     * const twistId = await this.tools.twists.create();
+     * const callback = await this.callback(this.onLogs);
      *
      * // Subscribe to logs
-     * await this.twist.watchLogs(twistId, callback);
+     * await this.tools.twists.watchLogs(twistId, callback);
      *
      * // Implement handler
      * async onLogs(logs: Log[]) {

package/dist/tools/twists.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twists.d.ts","sourceRoot":"","sources":["../../src/tools/twists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,MAAO,SAAQ,KAAK;IACxC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IAEH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IAEH,QAAQ,CAAC,MAAM,CACb,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QAChD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,CACA;QACE,MAAM,EAAE,MAAM,CAAC;KAChB,GACD;QACE,MAAM,EAAE,WAAW,CAAC;KACrB,CACJ,GACA,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IAEH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CACvE"}
+{"version":3,"file":"twists.d.ts","sourceRoot":"","sources":["../../src/tools/twists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,MAAO,SAAQ,KAAK;IACxC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IAEH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IAEH,QAAQ,CAAC,MAAM,CACb,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QAChD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,CACA;QACE,MAAM,EAAE,MAAM,CAAC;KAChB,GACD;QACE,MAAM,EAAE,WAAW,CAAC;KACrB,CACJ,GACA,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IAEH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CACvE"}

package/dist/tools/twists.js

@@ -7,10 +7,10 @@ import { ITool } from "..";
  *
  * @example
  * ```typescript
- * class TwistBuilderTwist extends Twist {
+ * class TwistBuilderTwist extends Twist<TwistBuilderTwist> {
  *   build(build: ToolBuilder) {
  *    return {
- *      twists: build.get(Twists)
+ *      twists: build(Twists)
  *    }
  *   }
  *

package/dist/tools/twists.js.map

@@ -1 +1 @@
-{"version":3,"file":"twists.js","sourceRoot":"","sources":["../../src/tools/twists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,EAAE,MAAM,IAAI,CAAC;AAuD1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAgB,MAAO,SAAQ,KAAK;CAsJzC"}
+{"version":3,"file":"twists.js","sourceRoot":"","sources":["../../src/tools/twists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,EAAE,MAAM,IAAI,CAAC;AAuD1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAgB,MAAO,SAAQ,KAAK;CAuJzC"}

package/dist/twist-guide.d.ts

@@ -1,2 +1,2 @@
-export declare const TWIST_GUIDE = "# 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  \u251C\u2500 Has stable URL or ID?\n  \u2502   \u2514\u2500 Yes \u2192 Set Thread.source to the canonical URL/ID\n  \u2502             Create Thread (Plot handles deduplication automatically)\n  \u2502             Use Note.key for different note types:\n  \u2502               - \"description\" for main content\n  \u2502               - \"metadata\" for status/priority/assignee\n  \u2502               - \"comment-{id}\" for individual comments\n  \u2502\n  \u2514\u2500 No stable identifier OR need multiple Plot threads per external item?\n      \u2514\u2500 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  \u251C\u2500 Yes \u2192 Generate UUID with Uuid.Generate()\n  \u2502         Create new Thread with that UUID\n  \u2502         Store mapping: external_id \u2192 thread_uuid\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Look up mapping by external_id\n      \u251C\u2500 Found \u2192 Add Note to existing Thread using stored UUID\n      \u2514\u2500 Not found \u2192 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 \u2192 \"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` \u2014 Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2264 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 \u2014 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 declare const TWIST_GUIDE = "# 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 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.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **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`.\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  \u251C\u2500 Has stable URL or ID?\n  \u2502   \u2514\u2500 Yes \u2192 Save a link with `source` set to the canonical URL/ID\n  \u2502             (connectors: integrations.saveLink() \u2014 Plot handles\n  \u2502             deduplication automatically)\n  \u2502             Use Note.key for different note types:\n  \u2502               - \"description\" for main content\n  \u2502               - \"metadata\" for status/priority/assignee\n  \u2502               - \"comment-{id}\" for individual comments\n  \u2502\n  \u2514\u2500 No stable identifier OR need multiple Plot threads per external item?\n      \u2514\u2500 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  \u251C\u2500 Yes \u2192 Generate UUID with Uuid.Generate()\n  \u2502         Create new Thread with that UUID\n  \u2502         Store mapping: external_id \u2192 thread_uuid\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Look up mapping by external_id\n      \u251C\u2500 Found \u2192 Add Note to existing Thread using stored UUID\n      \u2514\u2500 Not found \u2192 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 Note,\n  type ToolBuilder,\n  Twist,\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() {\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 threads, notes, focuses, 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.runTask()`)\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(context?: { actor: Actor })\n\nCalled 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.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate() {\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 Setup Thread for Later (optional):**\n\n```typescript\nasync activate() {\n  const threadId = await this.tools.plot.createThread({\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 (lifecycle overrides)\n\nTwists respond to events by overriding lifecycle methods inherited from the `Twist` base class. No registration is needed \u2014 declare Plot access in `build()` and the runtime routes events for threads your twist created:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n  },\n}),\n\n// Called when a thread created by this twist is updated\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded: Record<Tag, ActorId[]>; tagsRemoved: Record<Tag, ActorId[]> }): Promise<void> {\n  // Push the change to the external system\n  await externalApi.updateItem(thread.meta?.externalId, { title: thread.title });\n}\n\n// Called when a note is created on a thread created by this twist.\n// Notes created by the twist itself are filtered out automatically.\nasync onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops with other twists\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 \u2192 \"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\nFor a fully conversational twist, set `note.handler` instead of `intents` \u2014 every mention is then routed directly to that one method (`(note: Note) => Promise<void>`), skipping intent matching. `handler` and `intents` are mutually exclusive.\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` \u2014 Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` \u2014 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 (override onThreadUpdated / onNoteCreated)\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\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 \u2014 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 \u2014 use actionCallback, not callback)\nconst token = await this.actionCallback(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  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. 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.**\n\n```typescript\nimport { Connector, type ToolBuilder } from \"@plotday/twister\";\nimport {\n  AuthProvider,\n  type AuthToken,\n  type Authorization,\n  type Channel,\n  Integrations,\n} from \"@plotday/twister/tools/integrations\";\n\nexport default class MyConnector extends Connector<MyConnector> {\n  readonly provider = AuthProvider.Google;\n  readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n\n  build(build: ToolBuilder) {\n    return {\n      integrations: build(Integrations),\n    };\n  }\n\n  // List available resources after auth\n  async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> { ... }\n\n  // User enabled a resource\n  async onChannelEnabled(channel: Channel): Promise<void> { ... }\n\n  // User disabled a resource\n  async onChannelDisabled(channel: Channel): Promise<void> { ... }\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(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. Connectors save external items as links \u2014 `source` is the upsert key:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  // Create or update \u2014 Plot handles deduplication automatically\n  await this.tools.integrations.saveLink({\n    source: event.htmlLink,  // Canonical URL/ID for automatic deduplication\n    type: \"event\",\n    title: event.summary || \"(No title)\",\n    notes: event.description\n      ? [{\n          key: \"description\",  // This key enables note-level upserts\n          content: event.description,\n        }]\n      : [],\n  });\n}\n```\n\n`saveLink()` is available to Connectors only. A regular twist adding notes to an already-synced thread references it by source instead:\n\n```typescript\nawait this.tools.plot.createNote({\n  thread: { source: event.htmlLink },  // Reference the synced thread\n  key: \"summary\",\n  content: \"...\",\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 connector's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.\n\n```typescript\n// In your connector:\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 \u2264 100 items to stay under limit\n  for (const item of result.items) {\n    await this.tools.integrations.saveLink({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: \"item\",\n      title: item.title,\n      notes: [{\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  // Tip: integrations.saveLinks([...]) saves a whole page in one call,\n  // which counts as a single request against the execution budget.\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      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\nawait this.tools.integrations.saveLink({\n  source: event.url,\n  type: \"event\",\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**: Threads are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Threads 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 threads 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 `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 \u2014 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  if (comment.metadata?.plotNoteId) {\n    // Plot ID in metadata: the note originated in Plot (handles the race)\n    await this.tools.plot.updateNote({\n      id: comment.metadata.plotNoteId,\n      key: `comment-${comment.id}`,\n      content: comment.body,\n    });\n  } else {\n    // Otherwise upsert by thread source and note key\n    await this.tools.plot.createNote({\n      thread: { source: payload.itemUrl },\n      key: `comment-${comment.id}`,\n      content: comment.body,\n    });\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    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 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.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **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.\n- **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).\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- **Don't cache auth tokens** - Fetch tokens with `this.tools.integrations.get(channelId)` when needed; the Integrations tool manages storage and refresh.\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";
 //# sourceMappingURL=twist-guide.d.ts.map

package/dist/twist-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide.d.ts","sourceRoot":"","sources":["../src/twist-guide.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,y6wBAAsB,CAAC"}
+{"version":3,"file":"twist-guide.d.ts","sourceRoot":"","sources":["../src/twist-guide.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,gi0BAAsB,CAAC"}

package/dist/twist.d.ts

@@ -185,8 +185,8 @@ export declare abstract class Twist<TSelf> {
      * await this.set("handler_token", token);
      *
      * // Later, execute the callback
-     * const token = await this.get<string>("handler_token");
-     * await this.run(token, args);
+     * const token = await this.get<Callback>("handler_token");
+     * await this.run(token);
      * ```
      *
      * @template T - The type of value being stored (must be Serializable)

package/dist/twist.js

@@ -162,8 +162,8 @@ export class Twist {
      * await this.set("handler_token", token);
      *
      * // Later, execute the callback
-     * const token = await this.get<string>("handler_token");
-     * await this.run(token, args);
+     * const token = await this.get<Callback>("handler_token");
+     * await this.run(token);
      * ```
      *
      * @template T - The type of value being stored (must be Serializable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plotday/twister",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Plot Twist Creator - Build intelligent extensions that integrate and automate",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,6 +44,11 @@
       "types": "./dist/tag.d.ts",
       "default": "./dist/tag.js"
     },
+    "./facets": {
+      "@plotday/connector": "./src/facets.ts",
+      "types": "./dist/facets.d.ts",
+      "default": "./dist/facets.js"
+    },
     "./options": {
       "@plotday/connector": "./src/options.ts",
       "types": "./dist/options.d.ts",

package/src/connector.ts

@@ -216,8 +216,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 },
  *     ],
  *   }];
  *
@@ -547,17 +547,24 @@ export abstract class Connector<TSelf> extends Twist<TSelf> {
   }
 
   /**
-   * 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
@@ -566,9 +573,9 @@ export abstract class Connector<TSelf> extends Twist<TSelf> {
   onContactsChanged(
     thread: Thread,
     changes: {
-      added: Array<{ contact: Contact; role: string }>;
-      removed: Array<{ contact: Contact; role: string }>;
-      changed: Array<{ contact: Contact; from: string; to: string }>;
+      added: Array<{ contact: Contact; role: string | null }>;
+      removed: Array<{ contact: Contact; role: string | null }>;
+      changed: Array<{ contact: Contact; from: string | null; to: string | null }>;
     },
   ): Promise<void> {
     return Promise.resolve();

package/src/facets.ts

@@ -0,0 +1,40 @@
+/**
+ * Thread facets — heuristic, message-derived attributes used as internal
+ * classifier signal (never user-facing). A connector emits the intrinsic
+ * facets on the link it saves; the server stores them on the thread and the
+ * focus classifier filters on them.
+ *
+ * Facets are best-effort: a connector sets a dimension only when a heuristic
+ * is confident, leaving it `null` otherwise. The classifier never excludes a
+ * thread on a `null` facet.
+ *
+ * `relationship` (a sender's relationship to the viewing user) is intentionally
+ * NOT here: it is recipient-relative and evaluated live by the server, never
+ * emitted by a connector.
+ */
+
+/** The kind of content. Single-valued. */
+export type Format =
+  | "chat"
+  | "message"
+  | "reading"
+  | "notification"
+  | "receipt"
+  | "invoice"
+  | "promotion";
+
+/** Whether a person or a system produced the message. */
+export type Automation = "human" | "automated";
+
+/** How the user was addressed. */
+export type Reach = "direct" | "list";
+
+/**
+ * Intrinsic facets a connector may set on a `NewLink`. Each is nullable —
+ * omit (or set `null`) when no heuristic is confident.
+ */
+export type ThreadFacets = {
+  format: Format | null;
+  automation: Automation | null;
+  reach: Reach | null;
+};