@plotday/twister 0.37.0 → 0.39.0

package/dist/llm-docs/tools/plot.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true;\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the thread's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for threads and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with threads, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n}\n";
+declare const _default: "import {\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\ntype SearchResultBase = {\n  thread: { id: string; title: string | null };\n  priority: { id: string; title: string | null };\n  similarity: number;\n};\n\nexport type NoteSearchResult = SearchResultBase & {\n  type: 'note';\n  id: string;\n  content: string | null;\n};\n\nexport type LinkSearchResult = SearchResultBase & {\n  type: 'link';\n  id: string;\n  title: string | null;\n  sourceUrl: string | null;\n  content: string | null;\n};\n\nexport type SearchResult = NoteSearchResult | LinkSearchResult;\n\n/** Default number of search results returned */\nexport const SEARCH_DEFAULT_LIMIT = 10;\n/** Maximum number of search results allowed */\nexport const SEARCH_MAX_LIMIT = 30;\n\nexport type SearchOptions = {\n  /** Max results to return (default: 10, max: 30) */\n  limit?: number;\n  /** Minimum similarity score 0-1 (default: 0.3) */\n  threshold?: number;\n  /** Scope search to this priority + descendants (default: twist's installed priority). Must be within the twist's allowed scope. */\n  priorityId?: string;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n      /** When true, auto-mention this twist on new notes in threads where it authored content. */\n      defaultMention?: boolean;\n    };\n    note?: {\n      /** When true, auto-mention this twist on new notes in threads where it was @-mentioned. */\n      defaultMention?: boolean;\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true;\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n    /** Enable semantic search across notes and links in the twist's priority scope. */\n    search?: true;\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the thread's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for threads and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with threads, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n\n  /**\n   * Searches notes and links using semantic similarity.\n   *\n   * Requires `search: true` in Plot options.\n   *\n   * @param query - The search query text\n   * @param options - Optional search configuration\n   * @returns Promise resolving to array of search results ordered by similarity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;\n}\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

package/dist/llm-docs/tools/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,o7gBAAo7gB;AAAn8gB,wBAAo8gB"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,swkBAAswkB;AAArxkB,wBAAsxkB"}

package/dist/llm-docs/tools/plot.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true;\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the thread's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for threads and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with threads, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n}\n";
+export default "import {\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\ntype SearchResultBase = {\n  thread: { id: string; title: string | null };\n  priority: { id: string; title: string | null };\n  similarity: number;\n};\n\nexport type NoteSearchResult = SearchResultBase & {\n  type: 'note';\n  id: string;\n  content: string | null;\n};\n\nexport type LinkSearchResult = SearchResultBase & {\n  type: 'link';\n  id: string;\n  title: string | null;\n  sourceUrl: string | null;\n  content: string | null;\n};\n\nexport type SearchResult = NoteSearchResult | LinkSearchResult;\n\n/** Default number of search results returned */\nexport const SEARCH_DEFAULT_LIMIT = 10;\n/** Maximum number of search results allowed */\nexport const SEARCH_MAX_LIMIT = 30;\n\nexport type SearchOptions = {\n  /** Max results to return (default: 10, max: 30) */\n  limit?: number;\n  /** Minimum similarity score 0-1 (default: 0.3) */\n  threshold?: number;\n  /** Scope search to this priority + descendants (default: twist's installed priority). Must be within the twist's allowed scope. */\n  priorityId?: string;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n      /** When true, auto-mention this twist on new notes in threads where it authored content. */\n      defaultMention?: boolean;\n    };\n    note?: {\n      /** When true, auto-mention this twist on new notes in threads where it was @-mentioned. */\n      defaultMention?: boolean;\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true;\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n    /** Enable semantic search across notes and links in the twist's priority scope. */\n    search?: true;\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the thread's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for threads and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with threads, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n\n  /**\n   * Searches notes and links using semantic similarity.\n   *\n   * Requires `search: true` in Plot options.\n   *\n   * @param query - The search query text\n   * @param options - Optional search configuration\n   * @returns Promise resolving to array of search results ordered by similarity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;\n}\n";
 //# sourceMappingURL=plot.js.map

package/dist/llm-docs/tools/plot.js.map

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,o7gBAAo7gB,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,swkBAAswkB,CAAC"}

package/dist/llm-docs/twist-guide-template.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: cli/templates/AGENTS.template.md
  */
-declare const _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  \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): Promise<void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment\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## 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):\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 \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";
+declare const _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  \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): Promise<void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment\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):\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 \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 default _default;
 //# sourceMappingURL=twist-guide-template.d.ts.map

package/dist/llm-docs/twist-guide-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,sntBAAk8sB;AAAj9sB,wBAAk9sB"}
+{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,0yvBAAumvB;AAAtnvB,wBAAunvB"}

package/dist/llm-docs/twist-guide-template.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * 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): Promise<void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment\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## 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): Promise<void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment\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";
 //# sourceMappingURL=twist-guide-template.js.map

package/dist/llm-docs/twist-guide-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,k8sBAAk8sB,CAAC"}
+{"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,umvBAAumvB,CAAC"}

package/dist/plot.d.ts

@@ -172,7 +172,9 @@ export declare enum ActionType {
     /** Video conferencing links with provider-specific handling */
     conferencing = "conferencing",
     /** File attachment links stored in R2 */
-    file = "file"
+    file = "file",
+    /** Thread reference links for navigating to related threads */
+    thread = "thread"
 }
 /**
  * Video conferencing providers for conferencing links.
@@ -274,6 +276,11 @@ export type Action = {
     fileSize: number;
     /** MIME type of the file */
     mimeType: string;
+} | {
+    /** Thread reference action for navigating to a related thread */
+    type: ActionType.thread;
+    /** UUID of the referenced thread */
+    threadId: Uuid;
 };
 /**
  * Represents metadata about a thread, typically from an external system.
@@ -358,6 +365,8 @@ type ThreadFields = ThreadCommon & {
     priority: Priority;
     /** The schedule associated with this thread, if any */
     schedule?: Schedule;
+    /** Source-specific metadata from the thread's link, populated on callbacks */
+    meta?: ThreadMeta;
 };
 export type Thread = ThreadFields;
 export type ThreadWithNotes = Thread & {

package/dist/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"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"}

package/dist/plot.js

@@ -40,6 +40,8 @@ export var ActionType;
     ActionType["conferencing"] = "conferencing";
     /** File attachment links stored in R2 */
     ActionType["file"] = "file";
+    /** Thread reference links for navigating to related threads */
+    ActionType["thread"] = "thread";
 })(ActionType || (ActionType = {}));
 /**
  * Video conferencing providers for conferencing links.

package/dist/plot.js.map

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAsEpC;;GAEG;AACH,MAAM,CAAN,IAAY,UAiBX;AAjBD,WAAY,UAAU;IACpB,uBAAuB;IACvB,mDAAY,CAAA;IACZ,+BAA+B;IAC/B,iEAAmB,CAAA;IACnB,6BAA6B;IAC7B,2DAAgB,CAAA;IAChB,6BAA6B;IAC7B,mDAAY,CAAA;IACZ,2BAA2B;IAC3B,2DAAgB,CAAA;IAChB,4BAA4B;IAC5B,2DAAgB,CAAA;IAChB,qBAAqB;IACrB,+CAAU,CAAA;IACV,6BAA6B;IAC7B,uDAAc,CAAA;AAChB,CAAC,EAjBW,UAAU,KAAV,UAAU,QAiBrB;AAmED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,UAWX;AAXD,WAAY,UAAU;IACpB,8CAA8C;IAC9C,mCAAqB,CAAA;IACrB,mDAAmD;IACnD,2BAAa,CAAA;IACb,+DAA+D;IAC/D,mCAAqB,CAAA;IACrB,+DAA+D;IAC/D,2CAA6B,CAAA;IAC7B,yCAAyC;IACzC,2BAAa,CAAA;AACf,CAAC,EAXW,UAAU,KAAV,UAAU,QAWrB;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAWX;AAXD,WAAY,oBAAoB;IAC9B,kBAAkB;IAClB,iDAAyB,CAAA;IACzB,WAAW;IACX,qCAAa,CAAA;IACb,sBAAsB;IACtB,yDAAiC,CAAA;IACjC,kBAAkB;IAClB,uCAAe,CAAA;IACf,6CAA6C;IAC7C,uCAAe,CAAA;AACjB,CAAC,EAXW,oBAAoB,KAApB,oBAAoB,QAW/B;AAqhBD;;;;;GAKG;AACH,MAAM,CAAN,IAAY,SAOX;AAPD,WAAY,SAAS;IACnB,qCAAqC;IACrC,yCAAI,CAAA;IACJ,2CAA2C;IAC3C,+CAAO,CAAA;IACP,0CAA0C;IAC1C,2CAAK,CAAA;AACP,CAAC,EAPW,SAAS,KAAT,SAAS,QAOpB"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAsEpC;;GAEG;AACH,MAAM,CAAN,IAAY,UAiBX;AAjBD,WAAY,UAAU;IACpB,uBAAuB;IACvB,mDAAY,CAAA;IACZ,+BAA+B;IAC/B,iEAAmB,CAAA;IACnB,6BAA6B;IAC7B,2DAAgB,CAAA;IAChB,6BAA6B;IAC7B,mDAAY,CAAA;IACZ,2BAA2B;IAC3B,2DAAgB,CAAA;IAChB,4BAA4B;IAC5B,2DAAgB,CAAA;IAChB,qBAAqB;IACrB,+CAAU,CAAA;IACV,6BAA6B;IAC7B,uDAAc,CAAA;AAChB,CAAC,EAjBW,UAAU,KAAV,UAAU,QAiBrB;AAmED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,UAaX;AAbD,WAAY,UAAU;IACpB,8CAA8C;IAC9C,mCAAqB,CAAA;IACrB,mDAAmD;IACnD,2BAAa,CAAA;IACb,+DAA+D;IAC/D,mCAAqB,CAAA;IACrB,+DAA+D;IAC/D,2CAA6B,CAAA;IAC7B,yCAAyC;IACzC,2BAAa,CAAA;IACb,+DAA+D;IAC/D,+BAAiB,CAAA;AACnB,CAAC,EAbW,UAAU,KAAV,UAAU,QAarB;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAWX;AAXD,WAAY,oBAAoB;IAC9B,kBAAkB;IAClB,iDAAyB,CAAA;IACzB,WAAW;IACX,qCAAa,CAAA;IACb,sBAAsB;IACtB,yDAAiC,CAAA;IACjC,kBAAkB;IAClB,uCAAe,CAAA;IACf,6CAA6C;IAC7C,uCAAe,CAAA;AACjB,CAAC,EAXW,oBAAoB,KAApB,oBAAoB,QAW/B;AA6hBD;;;;;GAKG;AACH,MAAM,CAAN,IAAY,SAOX;AAPD,WAAY,SAAS;IACnB,qCAAqC;IACrC,yCAAI,CAAA;IACJ,2CAA2C;IAC3C,+CAAO,CAAA;IACP,0CAA0C;IAC1C,2CAAK,CAAA;AACP,CAAC,EAPW,SAAS,KAAT,SAAS,QAOpB"}

package/dist/tools/ai.d.ts

@@ -63,6 +63,12 @@ import { ITool } from "..";
  * ```
  */
 export declare abstract class AI extends ITool {
+    /**
+     * Returns which AI capabilities are currently available.
+     * Check this before calling prompt() or embed() to gracefully
+     * handle cases where AI is disabled by the user.
+     */
+    abstract available(): AICapabilities;
     /**
      * Sends a request to an AI model and returns the response using the Vercel AI SDK.
      *
@@ -140,6 +146,18 @@ export declare abstract class AI extends ITool {
      */
     abstract prompt<TOOLS extends AIToolSet, SCHEMA extends TSchema = never>(request: AIRequest<TOOLS, SCHEMA>): Promise<AIResponse<TOOLS, SCHEMA>>;
 }
+/** Options for configuring AI tool usage in a twist. */
+export type AIOptions = {
+    /** Whether AI is required for this twist to function. Default: true */
+    required?: boolean;
+};
+/** Describes which AI capabilities are currently available to this twist. */
+export type AICapabilities = {
+    /** Whether AI prompting (text generation) is available. */
+    prompt: boolean;
+    /** Whether AI embedding generation is available. */
+    embed: boolean;
+};
 /**
  * Model preferences for selecting an AI model based on performance and cost requirements.
  * This allows Plot to match those preferences with user preferences (such as preferred or