@plotday/twister 0.27.0 → 0.28.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  createdAt: 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  /** 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):** An assignee is required. If not explicitly provided when creating\n   * an action, the assignee will default to the user who installed the twist (the twist owner).\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action with explicit assignee\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   *\n   * // Create action with auto-assignment (defaults to twist owner)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee will be set automatically to twist owner\n   * };\n   *\n   * // Update assignee\n   * await plot.updateActivity({\n   *   id: activityId,\n   *   assignee: {\n   *     id: newUserId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Bob\"\n   *   }\n   * });\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  doneAt: 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 a NewActivity of type 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   * @example\n   * ```typescript\n   * // \"Do Now\" - defaults to current time when start is omitted\n   * await this.tools.plot.createActivity({ type: ActivityType.Action, title: \"Urgent task\" });\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\" - unscheduled backlog item\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null\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: Scheduling Defaults for Actions**\n *\n * When creating an Activity of type `Action`, the `start` field determines its scheduling state:\n * - **Omit `start`** \u2192 Defaults to current time \u2192 \"Do Now\" (appears in today's actionable list)\n * - **Set `start: null`** \u2192 Unscheduled \u2192 \"Do Someday\" (backlog item, no specific time)\n * - **Set `start` to future Date** \u2192 Scheduled \u2192 \"Do Later\" (appears on that date)\n *\n * For most external task integrations (project management, issue trackers), use `start: null`\n * to create backlog items unless the task is explicitly marked as current/active.\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\" - Action defaults to current time (actionable today)\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // Omitting start defaults to new Date()\n * };\n *\n * // \"Do Someday\" - Backlog item (recommended for most synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null  // Explicitly set to null for backlog\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\" | \"assignee\" | \"type\" | \"priority\" | \"tags\" | \"mentions\"\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    /**\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 = Pick<Activity, \"id\"> &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"doneAt\"\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  /** 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 * The id field can be optionally provided by tools for tracking purposes.\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\">\n> & {\n  /** Reference to the parent activity (required) */\n  activity: Pick<Activity, \"id\">;\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 */\nexport type NoteUpdate = Pick<Note, \"id\"> &\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 { 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";
 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,+vxBAAutxB;AAAtuxB,wBAAuuxB"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,iv2BAAgr2B;AAA/r2B,wBAAgs2B"}

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  createdAt: 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  /** 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):** An assignee is required. If not explicitly provided when creating\n   * an action, the assignee will default to the user who installed the twist (the twist owner).\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action with explicit assignee\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   *\n   * // Create action with auto-assignment (defaults to twist owner)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee will be set automatically to twist owner\n   * };\n   *\n   * // Update assignee\n   * await plot.updateActivity({\n   *   id: activityId,\n   *   assignee: {\n   *     id: newUserId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Bob\"\n   *   }\n   * });\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  doneAt: 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 a NewActivity of type 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   * @example\n   * ```typescript\n   * // \"Do Now\" - defaults to current time when start is omitted\n   * await this.tools.plot.createActivity({ type: ActivityType.Action, title: \"Urgent task\" });\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\" - unscheduled backlog item\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null\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: Scheduling Defaults for Actions**\n *\n * When creating an Activity of type `Action`, the `start` field determines its scheduling state:\n * - **Omit `start`** → Defaults to current time → \"Do Now\" (appears in today's actionable list)\n * - **Set `start: null`** → Unscheduled → \"Do Someday\" (backlog item, no specific time)\n * - **Set `start` to future Date** → Scheduled → \"Do Later\" (appears on that date)\n *\n * For most external task integrations (project management, issue trackers), use `start: null`\n * to create backlog items unless the task is explicitly marked as current/active.\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\" - Action defaults to current time (actionable today)\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // Omitting start defaults to new Date()\n * };\n *\n * // \"Do Someday\" - Backlog item (recommended for most synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null  // Explicitly set to null for backlog\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\" | \"assignee\" | \"type\" | \"priority\" | \"tags\" | \"mentions\"\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    /**\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 = Pick<Activity, \"id\"> &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"doneAt\"\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  /** 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 * The id field can be optionally provided by tools for tracking purposes.\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\">\n> & {\n  /** Reference to the parent activity (required) */\n  activity: Pick<Activity, \"id\">;\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 */\nexport type NoteUpdate = Pick<Note, \"id\"> &\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 { 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";
 //# 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,utxBAAutxB,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,gr2BAAgr2B,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, Symbols, and undefined values\n   * cannot be stored directly.\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this 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   * @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";
 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,62TAAm2T;AAAl3T,wBAAm3T"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,i9UAAw7U;AAAv8U,wBAAw8U"}

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, Symbols, and undefined values\n   * cannot be stored directly.\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this 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   * @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";
 //# 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,m2TAAm2T,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,w7UAAw7U,CAAC"}

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contacts. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   doneAt: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
+declare const _default: "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,ipcAAipc;AAAhqc,wBAAiqc"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,kscAAksc;AAAjtc,wBAAktc"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contacts. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   doneAt: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
+export default "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
 //# sourceMappingURL=plot.js.map

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

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