@plotday/twister 0.28.0 → 0.29.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 Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity 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 activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\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 * 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 activities,\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 activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\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       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\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 activity 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 activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, 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 complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.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<Note>;\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 notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-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<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\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 and fields to change\n   * @returns Promise that resolves when the update is complete\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   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities 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>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, 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";
+declare const _default: "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  type Tag,\n  Uuid,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity 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 activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\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 * 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 activities,\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 activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.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   *       activity: {\n   *         access: ActivityAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       activity: {\n   *         access: ActivityAccess.Create,\n   *         updated: this.onActivityUpdated\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *         created: this.onNoteCreated\n   *       },\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\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       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\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 activity 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 activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, 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 complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.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<Note>;\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 notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-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<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\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 and fields to change\n   * @returns Promise that resolves when the update is complete\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 an activity by ID or source.\n   *\n   * This method enables lookup of activities either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived activities\n   * are included in the results.\n   *\n   * @param activity - Activity lookup by ID or source\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivity(\n    activity: { id: Uuid } | { source: string }\n  ): Promise<Activity | 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 activity). 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 activities 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>;\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 activities, 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";
 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,kscAAksc;AAAjtc,wBAAktc"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,svfAAsvf;AAArwf,wBAAswf"}

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 Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity 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 activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\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 * 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 activities,\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 activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\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       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\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 activity 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 activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, 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 complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.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<Note>;\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 notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-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<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\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 and fields to change\n   * @returns Promise that resolves when the update is complete\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   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities 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>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, 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";
+export default "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  type Tag,\n  Uuid,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity 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 activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\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 * 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 activities,\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 activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.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   *       activity: {\n   *         access: ActivityAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       activity: {\n   *         access: ActivityAccess.Create,\n   *         updated: this.onActivityUpdated\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *         created: this.onNoteCreated\n   *       },\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\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       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\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 activity 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 activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, 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 complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.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<Note>;\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 notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-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<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\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 and fields to change\n   * @returns Promise that resolves when the update is complete\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 an activity by ID or source.\n   *\n   * This method enables lookup of activities either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived activities\n   * are included in the results.\n   *\n   * @param activity - Activity lookup by ID or source\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivity(\n    activity: { id: Uuid } | { source: string }\n  ): Promise<Activity | 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 activity). 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 activities 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>;\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 activities, 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";
 //# 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,kscAAksc,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,svfAAsvf,CAAC"}

package/dist/llm-docs/tools/store.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 { ITool } from \"..\";\n\n/**\n * Built-in tool for persistent key-value storage.\n *\n * The Store tool provides twists and tools with a simple, persistent storage\n * mechanism that survives worker restarts and invocations. Each twist/tool\n * instance gets its own isolated storage namespace.\n *\n * **Note:** Store methods are also available directly on Twist and Tool classes\n * via `this.get()`, `this.set()`, `this.clear()`, and `this.clearAll()`.\n * This is the recommended approach for most use cases.\n *\n * **Storage Characteristics:**\n * - Persistent across worker restarts\n * - Isolated per twist/tool instance\n * - Supports any JSON-serializable data\n * - Async operations for scalability\n *\n * **Use Cases:**\n * - Storing authentication tokens\n * - Caching configuration data\n * - Maintaining sync state\n * - Persisting user preferences\n * - Tracking processing checkpoints\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool {\n *   async saveAuthToken(provider: string, token: string) {\n *     // Using built-in set method (recommended)\n *     await this.set(`auth_token_${provider}`, token);\n *   }\n *\n *   async getAuthToken(provider: string): Promise<string | null> {\n *     // Using built-in get method (recommended)\n *     return await this.get<string>(`auth_token_${provider}`);\n *   }\n *\n *   async clearAllTokens() {\n *     // Using built-in clearAll method (recommended)\n *     await this.clearAll();\n *   }\n * }\n * ```\n */\nexport abstract class Store extends ITool {\n  /**\n   * Retrieves a value from storage by key.\n   *\n   * Returns the stored value deserialized to the specified type,\n   * or null if the key doesn't exist or the value is null.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get<T>(key: string): Promise<T | null>;\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be JSON-serialized and stored persistently.\n   * Any existing value at the same key will be overwritten.\n   *\n   * **Handling undefined values:**\n   * - Object keys with undefined values are automatically removed\n   * - Arrays with undefined elements will throw a validation error\n   * - Use null instead of undefined for array elements\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   *\n   * @example\n   * ```typescript\n   * // Object keys with undefined are removed\n   * await this.set('data', { name: 'test', optional: undefined });\n   * // Stores: { name: 'test' }\n   *\n   * // Arrays with undefined throw errors - use null instead\n   * await this.set('items', [1, null, 3]); // \u2705 Works\n   * await this.set('items', [1, undefined, 3]); // \u274C Throws error\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract set<T>(key: string, value: T): Promise<void>;\n\n  /**\n   * Removes a specific key from storage.\n   *\n   * After this operation, get() calls for this key will return null.\n   * No error is thrown if the key doesn't exist.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract clear(key: string): Promise<void>;\n\n  /**\n   * Removes all keys from this storage instance.\n   *\n   * This operation clears all data stored by this twist/tool instance\n   * but does not affect storage for other twists or tools.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  abstract clearAll(): Promise<void>;\n}\n";
+declare const _default: "import { ITool, type Serializable } from \"..\";\n\n/**\n * Built-in tool for persistent key-value storage.\n *\n * The Store tool provides twists and tools with a simple, persistent storage\n * mechanism that survives worker restarts and invocations. Each twist/tool\n * instance gets its own isolated storage namespace.\n *\n * **Note:** Store methods are also available directly on Twist and Tool classes\n * via `this.get()`, `this.set()`, `this.clear()`, and `this.clearAll()`.\n * This is the recommended approach for most use cases.\n *\n * **Storage Characteristics:**\n * - Persistent across worker restarts\n * - Isolated per twist/tool instance\n * - Supports SuperJSON-serializable data (see below)\n * - Async operations for scalability\n *\n * **Supported Data Types (via SuperJSON):**\n * - Primitives: string, number, boolean, null, undefined\n * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt\n * - Collections: Arrays and objects (recursively)\n *\n * **NOT Supported (will throw validation errors):**\n * - Functions (use callback tokens instead - see Callbacks tool)\n * - Symbols\n * - Circular references\n * - Custom class instances\n *\n * **Use Cases:**\n * - Storing authentication tokens\n * - Caching configuration data\n * - Maintaining sync state\n * - Persisting user preferences\n * - Tracking processing checkpoints\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool {\n *   async saveAuthToken(provider: string, token: string) {\n *     // Using built-in set method (recommended)\n *     await this.set(`auth_token_${provider}`, token);\n *   }\n *\n *   async getAuthToken(provider: string): Promise<string | null> {\n *     // Using built-in get method (recommended)\n *     return await this.get<string>(`auth_token_${provider}`);\n *   }\n *\n *   async clearAllTokens() {\n *     // Using built-in clearAll method (recommended)\n *     await this.clearAll();\n *   }\n * }\n * ```\n */\nexport abstract class Store extends ITool {\n  /**\n   * Retrieves a value from storage by key.\n   *\n   * Returns the stored value deserialized to the specified type,\n   * or null if the key doesn't exist or the value is null.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get<T extends Serializable>(key: string): Promise<T | null>;\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * Any existing value at the same key will be overwritten.\n   *\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   *\n   * @example\n   * ```typescript\n   * // Date objects are preserved\n   * await this.set('sync_state', {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // undefined is now supported\n   * await this.set('data', { name: 'test', optional: undefined }); // \u2705 Works\n   *\n   * // Arrays with undefined are supported\n   * await this.set('items', [1, undefined, 3]); // \u2705 Works\n   * await this.set('items', [1, null, 3]); // \u2705 Also works\n   *\n   * // Maps and Sets are supported\n   * await this.set('mapping', new Map([['key', 'value']])); // \u2705 Works\n   * await this.set('tags', new Set(['tag1', 'tag2'])); // \u2705 Works\n   *\n   * // Functions are NOT supported - use callback tokens instead\n   * const token = await this.callback(this.myFunction);\n   * await this.set('callback_ref', token); // \u2705 Use callback token\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract set<T extends Serializable>(key: string, value: T): Promise<void>;\n\n  /**\n   * Removes a specific key from storage.\n   *\n   * After this operation, get() calls for this key will return null.\n   * No error is thrown if the key doesn't exist.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract clear(key: string): Promise<void>;\n\n  /**\n   * Removes all keys from this storage instance.\n   *\n   * This operation clears all data stored by this twist/tool instance\n   * but does not affect storage for other twists or tools.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  abstract clearAll(): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,g3HAAs2H;AAAr3H,wBAAs3H"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,s9JAAw7J;AAAv8J,wBAAw8J"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { ITool } from \"..\";\n\n/**\n * Built-in tool for persistent key-value storage.\n *\n * The Store tool provides twists and tools with a simple, persistent storage\n * mechanism that survives worker restarts and invocations. Each twist/tool\n * instance gets its own isolated storage namespace.\n *\n * **Note:** Store methods are also available directly on Twist and Tool classes\n * via `this.get()`, `this.set()`, `this.clear()`, and `this.clearAll()`.\n * This is the recommended approach for most use cases.\n *\n * **Storage Characteristics:**\n * - Persistent across worker restarts\n * - Isolated per twist/tool instance\n * - Supports any JSON-serializable data\n * - Async operations for scalability\n *\n * **Use Cases:**\n * - Storing authentication tokens\n * - Caching configuration data\n * - Maintaining sync state\n * - Persisting user preferences\n * - Tracking processing checkpoints\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool {\n *   async saveAuthToken(provider: string, token: string) {\n *     // Using built-in set method (recommended)\n *     await this.set(`auth_token_${provider}`, token);\n *   }\n *\n *   async getAuthToken(provider: string): Promise<string | null> {\n *     // Using built-in get method (recommended)\n *     return await this.get<string>(`auth_token_${provider}`);\n *   }\n *\n *   async clearAllTokens() {\n *     // Using built-in clearAll method (recommended)\n *     await this.clearAll();\n *   }\n * }\n * ```\n */\nexport abstract class Store extends ITool {\n  /**\n   * Retrieves a value from storage by key.\n   *\n   * Returns the stored value deserialized to the specified type,\n   * or null if the key doesn't exist or the value is null.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get<T>(key: string): Promise<T | null>;\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be JSON-serialized and stored persistently.\n   * Any existing value at the same key will be overwritten.\n   *\n   * **Handling undefined values:**\n   * - Object keys with undefined values are automatically removed\n   * - Arrays with undefined elements will throw a validation error\n   * - Use null instead of undefined for array elements\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   *\n   * @example\n   * ```typescript\n   * // Object keys with undefined are removed\n   * await this.set('data', { name: 'test', optional: undefined });\n   * // Stores: { name: 'test' }\n   *\n   * // Arrays with undefined throw errors - use null instead\n   * await this.set('items', [1, null, 3]); // ✅ Works\n   * await this.set('items', [1, undefined, 3]); // ❌ Throws error\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract set<T>(key: string, value: T): Promise<void>;\n\n  /**\n   * Removes a specific key from storage.\n   *\n   * After this operation, get() calls for this key will return null.\n   * No error is thrown if the key doesn't exist.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract clear(key: string): Promise<void>;\n\n  /**\n   * Removes all keys from this storage instance.\n   *\n   * This operation clears all data stored by this twist/tool instance\n   * but does not affect storage for other twists or tools.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  abstract clearAll(): Promise<void>;\n}\n";
+export default "import { ITool, type Serializable } from \"..\";\n\n/**\n * Built-in tool for persistent key-value storage.\n *\n * The Store tool provides twists and tools with a simple, persistent storage\n * mechanism that survives worker restarts and invocations. Each twist/tool\n * instance gets its own isolated storage namespace.\n *\n * **Note:** Store methods are also available directly on Twist and Tool classes\n * via `this.get()`, `this.set()`, `this.clear()`, and `this.clearAll()`.\n * This is the recommended approach for most use cases.\n *\n * **Storage Characteristics:**\n * - Persistent across worker restarts\n * - Isolated per twist/tool instance\n * - Supports SuperJSON-serializable data (see below)\n * - Async operations for scalability\n *\n * **Supported Data Types (via SuperJSON):**\n * - Primitives: string, number, boolean, null, undefined\n * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt\n * - Collections: Arrays and objects (recursively)\n *\n * **NOT Supported (will throw validation errors):**\n * - Functions (use callback tokens instead - see Callbacks tool)\n * - Symbols\n * - Circular references\n * - Custom class instances\n *\n * **Use Cases:**\n * - Storing authentication tokens\n * - Caching configuration data\n * - Maintaining sync state\n * - Persisting user preferences\n * - Tracking processing checkpoints\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool {\n *   async saveAuthToken(provider: string, token: string) {\n *     // Using built-in set method (recommended)\n *     await this.set(`auth_token_${provider}`, token);\n *   }\n *\n *   async getAuthToken(provider: string): Promise<string | null> {\n *     // Using built-in get method (recommended)\n *     return await this.get<string>(`auth_token_${provider}`);\n *   }\n *\n *   async clearAllTokens() {\n *     // Using built-in clearAll method (recommended)\n *     await this.clearAll();\n *   }\n * }\n * ```\n */\nexport abstract class Store extends ITool {\n  /**\n   * Retrieves a value from storage by key.\n   *\n   * Returns the stored value deserialized to the specified type,\n   * or null if the key doesn't exist or the value is null.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get<T extends Serializable>(key: string): Promise<T | null>;\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * Any existing value at the same key will be overwritten.\n   *\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   *\n   * @example\n   * ```typescript\n   * // Date objects are preserved\n   * await this.set('sync_state', {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // undefined is now supported\n   * await this.set('data', { name: 'test', optional: undefined }); // ✅ Works\n   *\n   * // Arrays with undefined are supported\n   * await this.set('items', [1, undefined, 3]); // ✅ Works\n   * await this.set('items', [1, null, 3]); // ✅ Also works\n   *\n   * // Maps and Sets are supported\n   * await this.set('mapping', new Map([['key', 'value']])); // ✅ Works\n   * await this.set('tags', new Set(['tag1', 'tag2'])); // ✅ Works\n   *\n   * // Functions are NOT supported - use callback tokens instead\n   * const token = await this.callback(this.myFunction);\n   * await this.set('callback_ref', token); // ✅ Use callback token\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract set<T extends Serializable>(key: string, value: T): Promise<void>;\n\n  /**\n   * Removes a specific key from storage.\n   *\n   * After this operation, get() calls for this key will return null.\n   * No error is thrown if the key doesn't exist.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract clear(key: string): Promise<void>;\n\n  /**\n   * Removes all keys from this storage instance.\n   *\n   * This operation clears all data stored by this twist/tool instance\n   * but does not affect storage for other twists or tools.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  abstract clearAll(): Promise<void>;\n}\n";
 //# sourceMappingURL=store.js.map

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

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

package/dist/llm-docs/tools/tasks.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 { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Run tool enables twists and tools to queue callbacks. This is especially\n * iportant for long-running operations and batch processing, since twists\n * operate within runtime limits. Run callbacks also benefit from automatic\n * retries on failure.\n *\n * **Note:** Run methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Break long operations into smaller batches\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch using built-in methods\n *     const callback = await this.callback(\"processBatch\", { batchNumber: 1 });\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(args: any, context: { batchNumber: number }) {\n *     // Process one batch of items\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // ... process items ...\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch using built-in methods\n *       const callback = await this.callback(\"processBatch\", {\n *         batchNumber: context.batchNumber + 1\n *       });\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(\"cleanupOldData\");\n *     return await this.run(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment with limited resources. Use this\n   * for breaking up long-running operations into manageable chunks.\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
+declare const _default: "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks. This is especially\n * important for long-running operations and batch processing, since twists\n * operate within runtime limits. Task callbacks also benefit from automatic\n * retries on failure.\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Break long operations into smaller batches\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch using built-in methods\n *     const callback = await this.callback(\"processBatch\", { batchNumber: 1 });\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(args: any, context: { batchNumber: number }) {\n *     // Process one batch of items\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // ... process items ...\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch using built-in methods\n *       const callback = await this.callback(\"processBatch\", {\n *         batchNumber: context.batchNumber + 1\n *       });\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(\"cleanupOldData\");\n *     return await this.run(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment with limited resources. Use this\n   * for breaking up long-running operations into manageable chunks.\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=tasks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/tasks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,qpHAAqpH;AAApqH,wBAAqqH"}
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/tasks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,gqHAAgqH;AAA/qH,wBAAgrH"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Run tool enables twists and tools to queue callbacks. This is especially\n * iportant for long-running operations and batch processing, since twists\n * operate within runtime limits. Run callbacks also benefit from automatic\n * retries on failure.\n *\n * **Note:** Run methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Break long operations into smaller batches\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch using built-in methods\n *     const callback = await this.callback(\"processBatch\", { batchNumber: 1 });\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(args: any, context: { batchNumber: number }) {\n *     // Process one batch of items\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // ... process items ...\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch using built-in methods\n *       const callback = await this.callback(\"processBatch\", {\n *         batchNumber: context.batchNumber + 1\n *       });\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(\"cleanupOldData\");\n *     return await this.run(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment with limited resources. Use this\n   * for breaking up long-running operations into manageable chunks.\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks. This is especially\n * important for long-running operations and batch processing, since twists\n * operate within runtime limits. Task callbacks also benefit from automatic\n * retries on failure.\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Break long operations into smaller batches\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch using built-in methods\n *     const callback = await this.callback(\"processBatch\", { batchNumber: 1 });\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(args: any, context: { batchNumber: number }) {\n *     // Process one batch of items\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // ... process items ...\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch using built-in methods\n *       const callback = await this.callback(\"processBatch\", {\n *         batchNumber: context.batchNumber + 1\n *       });\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(\"cleanupOldData\");\n *     return await this.run(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment with limited resources. Use this\n   * for breaking up long-running operations into manageable chunks.\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
 //# sourceMappingURL=tasks.js.map

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

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

package/dist/llm-docs/twist.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 { type Priority } from \"./plot\";\nimport { type ITool } from \"./tool\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type { InferTools, ToolBuilder, ToolShed } from \"./utils/types\";\n\n/**\n * Base class for all twists.\n *\n * Twists are activated in a Plot priority and have access to that priority and all\n * its descendants.\n *\n * Override build() to declare tool dependencies and lifecycle methods to handle events.\n *\n * @example\n * ```typescript\n * class FlatteringTwist extends Twist<FlatteringTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot),\n *     };\n *   }\n *\n *   async activate(priority: Pick<Priority, \"id\">) {\n *     // Initialize twist for the given priority\n *     await this.tools.plot.createActivity({\n *       type: ActivityType.Note,\n *       note: \"Hello, good looking!\",\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Twist<TSelf> {\n  constructor(protected id: string, private toolShed: ToolShed) {}\n\n  /**\n   * Gets the initialized tools for this twist.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools(): InferTools<TSelf> {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this twist.\n   * Return an object mapping tool names to build() promises.\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot),\n   *     calendar: build(GoogleCalendar, { apiKey: \"...\" }),\n   *   };\n   * }\n   * ```\n   */\n  abstract build(build: ToolBuilder): Record<string, Promise<ITool>>;\n\n  /**\n   * Creates a persistent callback to a method on this twist.\n   *\n   * ExtraArgs are strongly typed to match the method's signature after the first argument.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn as any, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this twist.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: []): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * **Important**: Values must be JSON-serializable. Functions, Symbols, and undefined values\n   * cannot be stored directly.\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this twist's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this twist.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called when the twist is activated for a specific priority.\n   *\n   * This method should contain initialization logic such as setting up\n   * initial activities, configuring webhooks, or establishing external connections.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  activate(priority: Pick<Priority, \"id\">): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a new version of the twist is deployed to an existing priority.\n   *\n   * This method should contain migration logic for updating old data structures\n   * or setting up new resources that weren't needed by the previous version.\n   * It is called with the new version for each active priorityTwist.\n   *\n   * @returns Promise that resolves when upgrade is complete\n   */\n  upgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist is removed from a priority.\n   *\n   * This method should contain cleanup logic such as removing webhooks,\n   * cleaning up external resources, or performing final data operations.\n   *\n   * @returns Promise that resolves when deactivation is complete\n   */\n  deactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+declare const _default: "import { type Priority, Uuid } from \"./plot\";\nimport { type ITool } from \"./tool\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type { InferTools, ToolBuilder, ToolShed } from \"./utils/types\";\n\n/**\n * Base class for all twists.\n *\n * Twists are activated in a Plot priority and have access to that priority and all\n * its descendants.\n *\n * Override build() to declare tool dependencies and lifecycle methods to handle events.\n *\n * @example\n * ```typescript\n * class FlatteringTwist extends Twist<FlatteringTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot),\n *     };\n *   }\n *\n *   async activate(priority: Pick<Priority, \"id\">) {\n *     // Initialize twist for the given priority\n *     await this.tools.plot.createActivity({\n *       type: ActivityType.Note,\n *       note: \"Hello, good looking!\",\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Twist<TSelf> {\n  constructor(protected id: Uuid, private toolShed: ToolShed) {}\n\n  /**\n   * Gets the initialized tools for this twist.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools(): InferTools<TSelf> {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this twist.\n   * Return an object mapping tool names to build() promises.\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot),\n   *     calendar: build(GoogleCalendar, { apiKey: \"...\" }),\n   *   };\n   * }\n   * ```\n   */\n  abstract build(build: ToolBuilder): Record<string, Promise<ITool>>;\n\n  /**\n   * Creates a persistent callback to a method on this twist.\n   *\n   * ExtraArgs are strongly typed to match the method's signature after the first argument.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn as any, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this twist.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: []): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends import(\"./index\").Serializable>(\n    key: string\n  ): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // \u2705 undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends import(\"./index\").Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this twist's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this twist.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called when the twist is activated for a specific priority.\n   *\n   * This method should contain initialization logic such as setting up\n   * initial activities, configuring webhooks, or establishing external connections.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  activate(priority: Pick<Priority, \"id\">): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a new version of the twist is deployed to an existing priority.\n   *\n   * This method should contain migration logic for updating old data structures\n   * or setting up new resources that weren't needed by the previous version.\n   * It is called with the new version for each active priorityTwist.\n   *\n   * @returns Promise that resolves when upgrade is complete\n   */\n  upgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist is removed from a priority.\n   *\n   * This method should contain cleanup logic such as removing webhooks,\n   * cleaning up external resources, or performing final data operations.\n   *\n   * @returns Promise that resolves when deactivation is complete\n   */\n  deactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
 export default _default;
 //# sourceMappingURL=twist.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,ohQAA0gQ;AAAzhQ,wBAA0hQ"}
+{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,swRAAkvR;AAAjwR,wBAAkwR"}

package/dist/llm-docs/twist.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { type Priority } from \"./plot\";\nimport { type ITool } from \"./tool\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type { InferTools, ToolBuilder, ToolShed } from \"./utils/types\";\n\n/**\n * Base class for all twists.\n *\n * Twists are activated in a Plot priority and have access to that priority and all\n * its descendants.\n *\n * Override build() to declare tool dependencies and lifecycle methods to handle events.\n *\n * @example\n * ```typescript\n * class FlatteringTwist extends Twist<FlatteringTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot),\n *     };\n *   }\n *\n *   async activate(priority: Pick<Priority, \"id\">) {\n *     // Initialize twist for the given priority\n *     await this.tools.plot.createActivity({\n *       type: ActivityType.Note,\n *       note: \"Hello, good looking!\",\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Twist<TSelf> {\n  constructor(protected id: string, private toolShed: ToolShed) {}\n\n  /**\n   * Gets the initialized tools for this twist.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools(): InferTools<TSelf> {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this twist.\n   * Return an object mapping tool names to build() promises.\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot),\n   *     calendar: build(GoogleCalendar, { apiKey: \"...\" }),\n   *   };\n   * }\n   * ```\n   */\n  abstract build(build: ToolBuilder): Record<string, Promise<ITool>>;\n\n  /**\n   * Creates a persistent callback to a method on this twist.\n   *\n   * ExtraArgs are strongly typed to match the method's signature after the first argument.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn as any, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this twist.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: []): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * **Important**: Values must be JSON-serializable. Functions, Symbols, and undefined values\n   * cannot be stored directly.\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this twist's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this twist.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called when the twist is activated for a specific priority.\n   *\n   * This method should contain initialization logic such as setting up\n   * initial activities, configuring webhooks, or establishing external connections.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  activate(priority: Pick<Priority, \"id\">): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a new version of the twist is deployed to an existing priority.\n   *\n   * This method should contain migration logic for updating old data structures\n   * or setting up new resources that weren't needed by the previous version.\n   * It is called with the new version for each active priorityTwist.\n   *\n   * @returns Promise that resolves when upgrade is complete\n   */\n  upgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist is removed from a priority.\n   *\n   * This method should contain cleanup logic such as removing webhooks,\n   * cleaning up external resources, or performing final data operations.\n   *\n   * @returns Promise that resolves when deactivation is complete\n   */\n  deactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+export default "import { type Priority, Uuid } from \"./plot\";\nimport { type ITool } from \"./tool\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type { InferTools, ToolBuilder, ToolShed } from \"./utils/types\";\n\n/**\n * Base class for all twists.\n *\n * Twists are activated in a Plot priority and have access to that priority and all\n * its descendants.\n *\n * Override build() to declare tool dependencies and lifecycle methods to handle events.\n *\n * @example\n * ```typescript\n * class FlatteringTwist extends Twist<FlatteringTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot),\n *     };\n *   }\n *\n *   async activate(priority: Pick<Priority, \"id\">) {\n *     // Initialize twist for the given priority\n *     await this.tools.plot.createActivity({\n *       type: ActivityType.Note,\n *       note: \"Hello, good looking!\",\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Twist<TSelf> {\n  constructor(protected id: Uuid, private toolShed: ToolShed) {}\n\n  /**\n   * Gets the initialized tools for this twist.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools(): InferTools<TSelf> {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this twist.\n   * Return an object mapping tool names to build() promises.\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot),\n   *     calendar: build(GoogleCalendar, { apiKey: \"...\" }),\n   *   };\n   * }\n   * ```\n   */\n  abstract build(build: ToolBuilder): Record<string, Promise<ITool>>;\n\n  /**\n   * Creates a persistent callback to a method on this twist.\n   *\n   * ExtraArgs are strongly typed to match the method's signature after the first argument.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn as any, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this twist.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: []): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends import(\"./index\").Serializable>(\n    key: string\n  ): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends import(\"./index\").Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this twist's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this twist.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called when the twist is activated for a specific priority.\n   *\n   * This method should contain initialization logic such as setting up\n   * initial activities, configuring webhooks, or establishing external connections.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  activate(priority: Pick<Priority, \"id\">): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a new version of the twist is deployed to an existing priority.\n   *\n   * This method should contain migration logic for updating old data structures\n   * or setting up new resources that weren't needed by the previous version.\n   * It is called with the new version for each active priorityTwist.\n   *\n   * @returns Promise that resolves when upgrade is complete\n   */\n  upgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist is removed from a priority.\n   *\n   * This method should contain cleanup logic such as removing webhooks,\n   * cleaning up external resources, or performing final data operations.\n   *\n   * @returns Promise that resolves when deactivation is complete\n   */\n  deactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
 //# sourceMappingURL=twist.js.map

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

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