@plotday/twister 0.28.0 → 0.29.0

package/dist/llm-docs/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 { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: string;\n  /** Human-readable title for the priority */\n  title: string;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Excludes the auto-generated ID field and adds an optional parentId\n * for creating hierarchical priority structures.\n */\nexport type NewPriority = Omit<Priority, \"id\"> & {\n  /** Optional ID of the parent priority for creating hierarchies */\n  parentId?: string;\n};\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   level: AuthLevel.User,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"\uD83D\uDCC5 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Authorization level (\"user\" or \"priority\") */\n      level: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: any;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is in draft state (not shown in do now view) */\n  draft: boolean;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[];\n};\n\nexport type Activity = ActivityCommon & {\n  /**\n   * Canonical URL for the item in an external system.\n   * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n   * When set, it uniquely identifies the activity within a priority tree.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** The type of activity (Note, Task, or Event) */\n  type: ActivityType;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):**\n   * - If not provided (undefined), defaults to the user who installed the twist (twist owner)\n   * - To create an **unassigned action**, explicitly set `assignee: null`\n   * - For synced tasks from external systems, typically set `assignee: null` for unassigned items\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action assigned to twist owner (default behavior)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee omitted \u2192 defaults to twist owner\n   * };\n   *\n   * // Create UNASSIGNED action (for backlog items)\n   * const backlogTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: null  // Explicitly set to null\n   * };\n   *\n   * // Create action with explicit assignee\n   * const assignedTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Deploy to production\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  done: Date | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating an Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * **Important for synced tasks**: When syncing unassigned backlog items from external systems,\n   * set BOTH `start: null` AND `assignee: null` to create unscheduled, unassigned actions.\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - assigned to twist owner, actionable immediately\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Urgent task\"\n   *   // start omitted \u2192 defaults to now\n   *   // assignee omitted \u2192 defaults to twist owner\n   * });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unassigned backlog item (common for synced tasks)\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null,      // Explicitly unscheduled\n   *   assignee: null    // Explicitly unassigned\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Array of additional occurrence dates to include in the recurrence pattern */\n  recurrenceDates: Date[] | null;\n  /**\n   * For recurring event exceptions, points to the root recurring activity.\n   * Used when an individual occurrence of a recurring event is modified.\n   */\n  recurrence: Activity | null;\n  /**\n   * For recurring event exceptions, the original occurrence date being overridden.\n   * Used to identify which occurrence of a recurring event this exception replaces.\n   */\n  occurrence: Date | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta source and score content\n * pickPriority: { \"meta.source\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** \u2192 Defaults to current time (now) \u2192 \"Do Now\"\n * - **`assignee` omitted** \u2192 Defaults to twist owner \u2192 Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` \u2192 \"Do Someday\" (unscheduled)\n * - `assignee: null` \u2192 Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted \u2192 defaults to now\n *   // assignee omitted \u2192 defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = Pick<Activity, \"type\"> &\n  Partial<\n    Omit<\n      Activity,\n      | \"author\"\n      | \"assignee\"\n      | \"type\"\n      | \"priority\"\n      | \"tags\"\n      | \"mentions\"\n      | \"id\"\n      | \"source\"\n    >\n  > &\n  (\n    | {\n        /**\n         * Unique identifier for the activity, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert activities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Canonical URL for the item in an external system.\n         * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n         * When set, it uniquely identifies the activity within a priority tree. This performs\n         * an upsert.\n         */\n        source: string;\n      }\n    | {\n        /* Neither id nor source is required. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - true (default): Activity is unread for all users in the priority\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\nexport type ActivityUpdate = (\n  | {\n      /**\n       * Unique identifier for the activity.\n       */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical URL for the item in an external system.\n       */\n      source: string;\n    }\n) &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"done\"\n      | \"title\"\n      | \"assignee\"\n      | \"draft\"\n      | \"private\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceDates\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n      | \"occurrence\"\n    >\n  > & {\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n  };\n\n/**\n * Represents a sync update from a tool.\n *\n * Tools that sync from external sources can send either:\n * - A new activity with notes (for newly discovered items)\n * - An update to an existing activity with optional new notes (for changed items)\n *\n * This allows tools to manage their own update detection logic locally,\n * providing Plot with the appropriate operation to perform.\n *\n * @example\n * ```typescript\n * // Send a new activity\n * const newItem: SyncUpdate = {\n *   type: ActivityType.Event,\n *   title: \"New Meeting\",\n *   id: Uuid.Generate(), // Tool-generated ID\n *   notes: [{ id: Uuid.Generate(), content: \"Description\" }]\n * };\n *\n * // Send an update to existing activity\n * const update: SyncUpdate = {\n *   activityId: existingActivityId,\n *   update: { title: \"Updated Meeting Title\" },\n *   notes: [{ id: Uuid.Generate(), content: \"New comment\" }]\n * };\n * ```\n */\nexport type SyncUpdate =\n  | NewActivityWithNotes\n  | {\n      /** ID of the activity to update */\n      activityId: string;\n      /** Optional updates to the activity itself */\n      update?: ActivityUpdate;\n      /** Optional new notes to add to the activity */\n      notes?: NewNote[];\n    };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /**\n   * Unique identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   * For example, \"description\" could identify the description note for a Jira issue.\n   */\n  key: string | null;\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the activity\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\">\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent activity (required) */\n    activity:\n      | Pick<Activity, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent activity as unread for users.\n     * - true (default): Activity becomes unread for users who haven't authored the note\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Note, \"draft\" | \"private\" | \"content\" | \"links\">> & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /** Email address (only included with ContactAccess.Read permission) */\n  email?: string;\n  /** Display name (undefined if not included due to permissions, null if not set) */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
+declare const _default: "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with activities, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Activity, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `type: ActivityType`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewActivity, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `type: ActivityType` in NewActivity\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new activity\n * const newActivity: NewActivity = {\n *   type: ActivityType.Action,  // Required\n *   title: \"Review PR\",          // Optional, provided\n *   assignee: null,              // Optional nullable, explicitly clearing\n *   // priority is omitted (undefined), will auto-select or use default\n * };\n *\n * // Updating an activity - only change what's specified\n * const update: ActivityUpdate = {\n *   id: activityId,\n *   done: new Date(),       // Mark as done\n *   assignee: null,         // Clear assignee\n *   // title is omitted, won't be changed\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   level: AuthLevel.User,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"\uD83D\uDCC5 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Authorization level (\"user\" or \"priority\") */\n      level: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is in draft state (not shown in do now view) */\n  draft: boolean;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[];\n};\n\nexport type Activity = ActivityCommon & {\n  /**\n   * Canonical URL for the item in an external system.\n   * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n   * When set, it uniquely identifies the activity within a priority tree.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** The type of activity (Note, Task, or Event) */\n  type: ActivityType;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):**\n   * - If not provided (undefined), defaults to the user who installed the twist (twist owner)\n   * - To create an **unassigned action**, explicitly set `assignee: null`\n   * - For synced tasks from external systems, typically set `assignee: null` for unassigned items\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action assigned to twist owner (default behavior)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee omitted \u2192 defaults to twist owner\n   * };\n   *\n   * // Create UNASSIGNED action (for backlog items)\n   * const backlogTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: null  // Explicitly set to null\n   * };\n   *\n   * // Create action with explicit assignee\n   * const assignedTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Deploy to production\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  done: Date | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating an Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * **Important for synced tasks**: When syncing unassigned backlog items from external systems,\n   * set BOTH `start: null` AND `assignee: null` to create unscheduled, unassigned actions.\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - assigned to twist owner, actionable immediately\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Urgent task\"\n   *   // start omitted \u2192 defaults to now\n   *   // assignee omitted \u2192 defaults to twist owner\n   * });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unassigned backlog item (common for synced tasks)\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null,      // Explicitly unscheduled\n   *   assignee: null    // Explicitly unassigned\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Array of additional occurrence dates to include in the recurrence pattern */\n  recurrenceDates: Date[] | null;\n  /**\n   * For recurring event exceptions, points to the root recurring activity.\n   * Used when an individual occurrence of a recurring event is modified.\n   */\n  recurrence: Activity | null;\n  /**\n   * For recurring event exceptions, the original occurrence date being overridden.\n   * Used to identify which occurrence of a recurring event this exception replaces.\n   */\n  occurrence: Date | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** \u2192 Defaults to current time (now) \u2192 \"Do Now\"\n * - **`assignee` omitted** \u2192 Defaults to twist owner \u2192 Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` \u2192 \"Do Someday\" (unscheduled)\n * - `assignee: null` \u2192 Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted \u2192 defaults to now\n *   // assignee omitted \u2192 defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = Pick<Activity, \"type\"> &\n  Partial<\n    Omit<\n      Activity,\n      | \"author\"\n      | \"assignee\"\n      | \"type\"\n      | \"priority\"\n      | \"tags\"\n      | \"mentions\"\n      | \"id\"\n      | \"source\"\n    >\n  > &\n  (\n    | {\n        /**\n         * Unique identifier for the activity, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert activities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Canonical URL for the item in an external system.\n         * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n         * When set, it uniquely identifies the activity within a priority tree. This performs\n         * an upsert.\n         */\n        source: string;\n      }\n    | {\n        /* Neither id nor source is required. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - true (default): Activity is unread for all users in the priority\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\nexport type ActivityUpdate = (\n  | {\n      /**\n       * Unique identifier for the activity.\n       */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical URL for the item in an external system.\n       */\n      source: string;\n    }\n) &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"done\"\n      | \"title\"\n      | \"assignee\"\n      | \"draft\"\n      | \"private\"\n      | \"archived\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceDates\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n      | \"occurrence\"\n    >\n  > & {\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n  };\n\n/**\n * Represents a sync update from a tool.\n *\n * Tools that sync from external sources can send either:\n * - A new activity with notes (for newly discovered items)\n * - An update to an existing activity with optional new notes (for changed items)\n *\n * This allows tools to manage their own update detection logic locally,\n * providing Plot with the appropriate operation to perform.\n *\n * @example\n * ```typescript\n * // Send a new activity\n * const newItem: SyncUpdate = {\n *   type: ActivityType.Event,\n *   title: \"New Meeting\",\n *   id: Uuid.Generate(), // Tool-generated ID\n *   notes: [{ id: Uuid.Generate(), content: \"Description\" }]\n * };\n *\n * // Send an update to existing activity\n * const update: SyncUpdate = {\n *   activityId: existingActivityId,\n *   update: { title: \"Updated Meeting Title\" },\n *   notes: [{ id: Uuid.Generate(), content: \"New comment\" }]\n * };\n * ```\n */\nexport type SyncUpdate =\n  | NewActivityWithNotes\n  | {\n      /** ID of the activity to update */\n      activityId: string;\n      /** Optional updates to the activity itself */\n      update?: ActivityUpdate;\n      /** Optional new notes to add to the activity */\n      notes?: NewNote[];\n    };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /**\n   * Unique identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   * For example, \"description\" could identify the description note for a Jira issue.\n   */\n  key: string | null;\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the activity\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\">\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent activity (required) */\n    activity:\n      | Pick<Activity, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent activity as unread for users.\n     * - true (default): Activity becomes unread for users who haven't authored the note\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<\n    Pick<Note, \"draft\" | \"private\" | \"archived\" | \"content\" | \"links\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,iv2BAAgr2B;AAA/r2B,wBAAgs2B"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,gj/BAA+++B;AAA9/+B,wBAA+/+B"}

package/dist/llm-docs/plot.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: string;\n  /** Human-readable title for the priority */\n  title: string;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Excludes the auto-generated ID field and adds an optional parentId\n * for creating hierarchical priority structures.\n */\nexport type NewPriority = Omit<Priority, \"id\"> & {\n  /** Optional ID of the parent priority for creating hierarchies */\n  parentId?: string;\n};\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   level: AuthLevel.User,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Authorization level (\"user\" or \"priority\") */\n      level: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: any;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is in draft state (not shown in do now view) */\n  draft: boolean;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[];\n};\n\nexport type Activity = ActivityCommon & {\n  /**\n   * Canonical URL for the item in an external system.\n   * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n   * When set, it uniquely identifies the activity within a priority tree.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** The type of activity (Note, Task, or Event) */\n  type: ActivityType;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):**\n   * - If not provided (undefined), defaults to the user who installed the twist (twist owner)\n   * - To create an **unassigned action**, explicitly set `assignee: null`\n   * - For synced tasks from external systems, typically set `assignee: null` for unassigned items\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action assigned to twist owner (default behavior)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee omitted → defaults to twist owner\n   * };\n   *\n   * // Create UNASSIGNED action (for backlog items)\n   * const backlogTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: null  // Explicitly set to null\n   * };\n   *\n   * // Create action with explicit assignee\n   * const assignedTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Deploy to production\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  done: Date | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating an Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * **Important for synced tasks**: When syncing unassigned backlog items from external systems,\n   * set BOTH `start: null` AND `assignee: null` to create unscheduled, unassigned actions.\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - assigned to twist owner, actionable immediately\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Urgent task\"\n   *   // start omitted → defaults to now\n   *   // assignee omitted → defaults to twist owner\n   * });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unassigned backlog item (common for synced tasks)\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null,      // Explicitly unscheduled\n   *   assignee: null    // Explicitly unassigned\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Array of additional occurrence dates to include in the recurrence pattern */\n  recurrenceDates: Date[] | null;\n  /**\n   * For recurring event exceptions, points to the root recurring activity.\n   * Used when an individual occurrence of a recurring event is modified.\n   */\n  recurrence: Activity | null;\n  /**\n   * For recurring event exceptions, the original occurrence date being overridden.\n   * Used to identify which occurrence of a recurring event this exception replaces.\n   */\n  occurrence: Date | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta source and score content\n * pickPriority: { \"meta.source\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** → Defaults to current time (now) → \"Do Now\"\n * - **`assignee` omitted** → Defaults to twist owner → Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` → \"Do Someday\" (unscheduled)\n * - `assignee: null` → Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted → defaults to now\n *   // assignee omitted → defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = Pick<Activity, \"type\"> &\n  Partial<\n    Omit<\n      Activity,\n      | \"author\"\n      | \"assignee\"\n      | \"type\"\n      | \"priority\"\n      | \"tags\"\n      | \"mentions\"\n      | \"id\"\n      | \"source\"\n    >\n  > &\n  (\n    | {\n        /**\n         * Unique identifier for the activity, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert activities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Canonical URL for the item in an external system.\n         * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n         * When set, it uniquely identifies the activity within a priority tree. This performs\n         * an upsert.\n         */\n        source: string;\n      }\n    | {\n        /* Neither id nor source is required. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - true (default): Activity is unread for all users in the priority\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\nexport type ActivityUpdate = (\n  | {\n      /**\n       * Unique identifier for the activity.\n       */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical URL for the item in an external system.\n       */\n      source: string;\n    }\n) &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"done\"\n      | \"title\"\n      | \"assignee\"\n      | \"draft\"\n      | \"private\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceDates\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n      | \"occurrence\"\n    >\n  > & {\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n  };\n\n/**\n * Represents a sync update from a tool.\n *\n * Tools that sync from external sources can send either:\n * - A new activity with notes (for newly discovered items)\n * - An update to an existing activity with optional new notes (for changed items)\n *\n * This allows tools to manage their own update detection logic locally,\n * providing Plot with the appropriate operation to perform.\n *\n * @example\n * ```typescript\n * // Send a new activity\n * const newItem: SyncUpdate = {\n *   type: ActivityType.Event,\n *   title: \"New Meeting\",\n *   id: Uuid.Generate(), // Tool-generated ID\n *   notes: [{ id: Uuid.Generate(), content: \"Description\" }]\n * };\n *\n * // Send an update to existing activity\n * const update: SyncUpdate = {\n *   activityId: existingActivityId,\n *   update: { title: \"Updated Meeting Title\" },\n *   notes: [{ id: Uuid.Generate(), content: \"New comment\" }]\n * };\n * ```\n */\nexport type SyncUpdate =\n  | NewActivityWithNotes\n  | {\n      /** ID of the activity to update */\n      activityId: string;\n      /** Optional updates to the activity itself */\n      update?: ActivityUpdate;\n      /** Optional new notes to add to the activity */\n      notes?: NewNote[];\n    };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /**\n   * Unique identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   * For example, \"description\" could identify the description note for a Jira issue.\n   */\n  key: string | null;\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the activity\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\">\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent activity (required) */\n    activity:\n      | Pick<Activity, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent activity as unread for users.\n     * - true (default): Activity becomes unread for users who haven't authored the note\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Note, \"draft\" | \"private\" | \"content\" | \"links\">> & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /** Email address (only included with ContactAccess.Read permission) */\n  email?: string;\n  /** Display name (undefined if not included due to permissions, null if not set) */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
+export default "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with activities, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Activity, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `type: ActivityType`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewActivity, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `type: ActivityType` in NewActivity\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new activity\n * const newActivity: NewActivity = {\n *   type: ActivityType.Action,  // Required\n *   title: \"Review PR\",          // Optional, provided\n *   assignee: null,              // Optional nullable, explicitly clearing\n *   // priority is omitted (undefined), will auto-select or use default\n * };\n *\n * // Updating an activity - only change what's specified\n * const update: ActivityUpdate = {\n *   id: activityId,\n *   done: new Date(),       // Mark as done\n *   assignee: null,         // Clear assignee\n *   // title is omitted, won't be changed\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   level: AuthLevel.User,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Authorization level (\"user\" or \"priority\") */\n      level: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is in draft state (not shown in do now view) */\n  draft: boolean;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[];\n};\n\nexport type Activity = ActivityCommon & {\n  /**\n   * Canonical URL for the item in an external system.\n   * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n   * When set, it uniquely identifies the activity within a priority tree.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** The type of activity (Note, Task, or Event) */\n  type: ActivityType;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):**\n   * - If not provided (undefined), defaults to the user who installed the twist (twist owner)\n   * - To create an **unassigned action**, explicitly set `assignee: null`\n   * - For synced tasks from external systems, typically set `assignee: null` for unassigned items\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action assigned to twist owner (default behavior)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee omitted → defaults to twist owner\n   * };\n   *\n   * // Create UNASSIGNED action (for backlog items)\n   * const backlogTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: null  // Explicitly set to null\n   * };\n   *\n   * // Create action with explicit assignee\n   * const assignedTask: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Deploy to production\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  done: Date | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating an Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * **Important for synced tasks**: When syncing unassigned backlog items from external systems,\n   * set BOTH `start: null` AND `assignee: null` to create unscheduled, unassigned actions.\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - assigned to twist owner, actionable immediately\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Urgent task\"\n   *   // start omitted → defaults to now\n   *   // assignee omitted → defaults to twist owner\n   * });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unassigned backlog item (common for synced tasks)\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null,      // Explicitly unscheduled\n   *   assignee: null    // Explicitly unassigned\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Array of additional occurrence dates to include in the recurrence pattern */\n  recurrenceDates: Date[] | null;\n  /**\n   * For recurring event exceptions, points to the root recurring activity.\n   * Used when an individual occurrence of a recurring event is modified.\n   */\n  recurrence: Activity | null;\n  /**\n   * For recurring event exceptions, the original occurrence date being overridden.\n   * Used to identify which occurrence of a recurring event this exception replaces.\n   */\n  occurrence: Date | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** → Defaults to current time (now) → \"Do Now\"\n * - **`assignee` omitted** → Defaults to twist owner → Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` → \"Do Someday\" (unscheduled)\n * - `assignee: null` → Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted → defaults to now\n *   // assignee omitted → defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = Pick<Activity, \"type\"> &\n  Partial<\n    Omit<\n      Activity,\n      | \"author\"\n      | \"assignee\"\n      | \"type\"\n      | \"priority\"\n      | \"tags\"\n      | \"mentions\"\n      | \"id\"\n      | \"source\"\n    >\n  > &\n  (\n    | {\n        /**\n         * Unique identifier for the activity, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert activities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Canonical URL for the item in an external system.\n         * For example, https://acme.atlassian.net/browse/PROJ-42 could represent a Jira issue.\n         * When set, it uniquely identifies the activity within a priority tree. This performs\n         * an upsert.\n         */\n        source: string;\n      }\n    | {\n        /* Neither id nor source is required. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - true (default): Activity is unread for all users in the priority\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\nexport type ActivityUpdate = (\n  | {\n      /**\n       * Unique identifier for the activity.\n       */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical URL for the item in an external system.\n       */\n      source: string;\n    }\n) &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"done\"\n      | \"title\"\n      | \"assignee\"\n      | \"draft\"\n      | \"private\"\n      | \"archived\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceDates\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n      | \"occurrence\"\n    >\n  > & {\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n  };\n\n/**\n * Represents a sync update from a tool.\n *\n * Tools that sync from external sources can send either:\n * - A new activity with notes (for newly discovered items)\n * - An update to an existing activity with optional new notes (for changed items)\n *\n * This allows tools to manage their own update detection logic locally,\n * providing Plot with the appropriate operation to perform.\n *\n * @example\n * ```typescript\n * // Send a new activity\n * const newItem: SyncUpdate = {\n *   type: ActivityType.Event,\n *   title: \"New Meeting\",\n *   id: Uuid.Generate(), // Tool-generated ID\n *   notes: [{ id: Uuid.Generate(), content: \"Description\" }]\n * };\n *\n * // Send an update to existing activity\n * const update: SyncUpdate = {\n *   activityId: existingActivityId,\n *   update: { title: \"Updated Meeting Title\" },\n *   notes: [{ id: Uuid.Generate(), content: \"New comment\" }]\n * };\n * ```\n */\nexport type SyncUpdate =\n  | NewActivityWithNotes\n  | {\n      /** ID of the activity to update */\n      activityId: string;\n      /** Optional updates to the activity itself */\n      update?: ActivityUpdate;\n      /** Optional new notes to add to the activity */\n      notes?: NewNote[];\n    };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /**\n   * Unique identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   * For example, \"description\" could identify the description note for a Jira issue.\n   */\n  key: string | null;\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the activity\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\">\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent activity (required) */\n    activity:\n      | Pick<Activity, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the activity. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent activity as unread for users.\n     * - true (default): Activity becomes unread for users who haven't authored the note\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<\n    Pick<Note, \"draft\" | \"private\" | \"archived\" | \"content\" | \"links\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
 //# sourceMappingURL=plot.js.map

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

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

package/dist/llm-docs/tool.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 { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\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   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\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<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...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 tool.\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?: any): 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 and Symbols cannot be stored.\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   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Object keys with undefined are automatically removed\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   * // Stores: { name: \"test\" }\n   *\n   * // \u2705 Arrays: use null for optional values\n   * await this.set(\"items\", [1, null, 3]);\n   *\n   * // \u274C Arrays with undefined throw errors\n   * await this.set(\"items\", [1, undefined, 3]); // Error!\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\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 tool'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 tool.\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 before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): 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 } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\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   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\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<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...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 tool.\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: any[]): 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>(key: string): 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   * // \u2705 Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // \u2705 Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\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>(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 tool'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 tool.\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 before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): 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=tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,i9UAAw7U;AAAv8U,wBAAw8U"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,y6VAA24V;AAA15V,wBAA25V"}

package/dist/llm-docs/tool.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 { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\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   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\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<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...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 tool.\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?: any): 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 and Symbols cannot be stored.\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   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Object keys with undefined are automatically removed\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   * // Stores: { name: \"test\" }\n   *\n   * // ✅ Arrays: use null for optional values\n   * await this.set(\"items\", [1, null, 3]);\n   *\n   * // ❌ Arrays with undefined throw errors\n   * await this.set(\"items\", [1, undefined, 3]); // Error!\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\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 tool'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 tool.\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 before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): 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 } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\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   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\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<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...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 tool.\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: any[]): 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>(key: string): 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   * // ✅ Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\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\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\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>(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 tool'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 tool.\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 before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): 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=tool.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,w7UAAw7U,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,24VAA24V,CAAC"}

package/dist/llm-docs/tools/network.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 AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: any;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook({\n *       callback: this.onCalendarEvent,\n *       extraArgs: [calendarId, \"google\"]\n *     });\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.callback - Function receiving (request, ...extraArgs)\n   * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook({\n   *   callback: this.onGmailNotification,\n   *   provider: AuthProvider.Google,\n   *   authorization: gmailAuth,\n   *   extraArgs: [\"inbox\"]\n   * });\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(options: {\n    callback: TCallback;\n    extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];\n    provider?: AuthProvider;\n    authorization?: Authorization;\n  }): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
+declare const _default: "import { ITool } from \"..\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\nimport { type NoFunctions, type JSONValue } from \"../utils/types\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: JSONValue;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook(\n *       {},\n *       this.onCalendarEvent,\n *       calendarId,\n *       \"google\"\n *     );\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @param callback - Function receiving (request, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook(\n   *   {\n   *     provider: AuthProvider.Google,\n   *     authorization: gmailAuth\n   *   },\n   *   this.onGmailNotification,\n   *   \"inbox\"\n   * );\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(\n    options: {\n      provider?: AuthProvider;\n      authorization?: Authorization;\n    },\n    callback: TCallback,\n    ...extraArgs: TCallback extends (req: any, ...rest: infer R) => any\n      ? NoFunctions<R>\n      : []\n  ): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=network.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,y/NAAy/N;AAAxgO,wBAAygO"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,snOAAsnO;AAAroO,wBAAsoO"}

package/dist/llm-docs/tools/network.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 AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: any;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook({\n *       callback: this.onCalendarEvent,\n *       extraArgs: [calendarId, \"google\"]\n *     });\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.callback - Function receiving (request, ...extraArgs)\n   * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook({\n   *   callback: this.onGmailNotification,\n   *   provider: AuthProvider.Google,\n   *   authorization: gmailAuth,\n   *   extraArgs: [\"inbox\"]\n   * });\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(options: {\n    callback: TCallback;\n    extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];\n    provider?: AuthProvider;\n    authorization?: Authorization;\n  }): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\nimport { type NoFunctions, type JSONValue } from \"../utils/types\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: JSONValue;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook(\n *       {},\n *       this.onCalendarEvent,\n *       calendarId,\n *       \"google\"\n *     );\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @param callback - Function receiving (request, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook(\n   *   {\n   *     provider: AuthProvider.Google,\n   *     authorization: gmailAuth\n   *   },\n   *   this.onGmailNotification,\n   *   \"inbox\"\n   * );\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(\n    options: {\n      provider?: AuthProvider;\n      authorization?: Authorization;\n    },\n    callback: TCallback,\n    ...extraArgs: TCallback extends (req: any, ...rest: infer R) => any\n      ? NoFunctions<R>\n      : []\n  ): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
 //# sourceMappingURL=network.js.map

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

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