@plotday/twister 0.34.0 → 0.36.0

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 { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with activities, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Activity, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `type: ActivityType`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewActivity, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `type: ActivityType` in NewActivity\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new activity\n * const newActivity: NewActivity = {\n *   type: ActivityType.Action,  // Required\n *   title: \"Review PR\",          // Optional, provided\n *   assignee: null,              // Optional nullable, explicitly clearing\n *   // priority is omitted (undefined), will auto-select or use default\n * };\n *\n * // Updating an activity - only change what's specified\n * const update: ActivityUpdate = {\n *   id: activityId,\n *   done: new Date(),       // Mark as done\n *   assignee: null,         // Clear assignee\n *   // title is omitted, won't be changed\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Kinds of activities. Used only for visual categorization (icon).\n */\nexport enum ActivityKind {\n  document = \"document\", // any external document or item in an external system\n  messages = \"messages\", // emails and chat threads\n  meeting = \"meeting\", // in-person meeting\n  videoconference = \"videoconference\",\n  phone = \"phone\",\n  focus = \"focus\",\n  meal = \"meal\",\n  exercise = \"exercise\",\n  family = \"family\",\n  travel = \"travel\",\n  social = \"social\",\n  entertainment = \"entertainment\",\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  /** File attachment links stored in R2 */\n  file = \"file\",\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 *   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      /** 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      /** File attachment link stored in R2 */\n      type: ActivityLinkType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is 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\n/**\n * Common fields shared by all activity types (Note, Action, Event).\n * Does not include the discriminant `type` field or type-specific fields like `done`.\n */\ntype ActivityFields = ActivityCommon & {\n  /**\n   * Globally unique, stable identifier for the item in an external system.\n   * MUST use immutable system-generated IDs, not human-readable slugs or titles.\n   *\n   * Recommended format: `${domain}:${type}:${id}`\n   *\n   * Examples:\n   *   - `linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b` (Linear issue by UUID)\n   *   - `jira:10001:issue:12345` (Jira issue by numeric ID with cloud ID)\n   *   - `gmail:thread:18d4e5f2a3b1c9d7` (Gmail thread by system ID)\n   *\n   * ⚠️ AVOID: URLs with mutable components like team names or issue keys\n   *   - Bad: `https://linear.app/team/issue/TEAM-123/title` (team and title can change)\n   *   - Bad: `jira:issue:PROJECT-42` (issue key can change)\n   *\n   * When set, uniquely identifies the activity within a priority tree for upsert operations.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** Optional kind for additional categorization within the activity */\n  kind: ActivityKind | null;\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   * When marking an activity as done, it becomes an Action; if no assignee is set,\n   * the twist owner is assigned automatically.\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  /**\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  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type Activity = ActivityFields &\n  (\n    | { type: ActivityType.Note }\n    | {\n        type: ActivityType.Action;\n        /**\n         * Timestamp when the activity was marked as complete. Null if not completed.\n         */\n        done: Date | null;\n      }\n    | { type: ActivityType.Event }\n  );\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Represents a specific instance of a recurring activity.\n * All field values are computed by merging the recurring activity's\n * defaults with any occurrence-specific overrides.\n */\nexport type ActivityOccurrence = {\n  /**\n   * Original date/datetime of this occurrence.\n   * Use start for the occurrence's current start time.\n   * Format: Date object or \"YYYY-MM-DD\" for all-day events.\n   */\n  occurrence: Date | string;\n\n  /**\n   * The recurring activity of which this is an occurrence.\n   */\n  activity: Activity;\n\n  /**\n   * Effective values for this occurrence (series defaults + overrides).\n   * These are the actual values that apply to this specific instance.\n   */\n  start: Date | string;\n  end: Date | string | null;\n  done: Date | null;\n  title: string;\n  /**\n   * Meta is merged, with the occurrence's meta taking precedence.\n   */\n  meta: ActivityMeta | null;\n\n  /**\n   * Tags for this occurrence (merged with the recurring tags).\n   */\n  tags: Tags;\n\n  /**\n   * True if the occurrence is archived.\n   */\n  archived: boolean;\n};\n\n/**\n * Type for creating or updating activity occurrences.\n *\n * Follows the same pattern as Activity/NewActivity:\n * - Required fields: `occurrence` (key) and `start` (for scheduling)\n * - Optional fields: All others from ActivityOccurrence\n * - Additional fields: `twistTags` for add/remove, `unread` for notification control\n *\n * @example\n * ```typescript\n * const activity: NewActivity = {\n *   type: ActivityType.Event,\n *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n *   occurrences: [\n *     {\n *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n *       start: new Date(\"2025-01-27T14:00:00Z\"),\n *       tags: { [Tag.Skip]: [user] }\n *     }\n *   ]\n * };\n * ```\n */\nexport type NewActivityOccurrence = Pick<\n  ActivityOccurrence,\n  \"occurrence\" | \"start\"\n> &\n  Partial<\n    Omit<ActivityOccurrence, \"occurrence\" | \"start\" | \"activity\" | \"tags\">\n  > & {\n    /**\n     * Tags specific to this occurrence.\n     * These replace any recurrence-level tags for this occurrence.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags on this occurrence.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Whether this occurrence should be marked as unread for users.\n     * - undefined/omitted (default): Occurrence is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Occurrence is explicitly unread for ALL users (use sparingly)\n     * - false: Occurrence is marked as read for all users\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Inline type for creating/updating occurrences within NewActivity/ActivityUpdate.\n * Used to specify occurrence-specific overrides when creating or updating a recurring activity.\n */\nexport type ActivityOccurrenceUpdate = Pick<\n  NewActivityOccurrence,\n  \"occurrence\"\n> &\n  Partial<Omit<NewActivityOccurrence, \"occurrence\" | \"activity\">>;\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** → Defaults to current time (now) → \"Do Now\"\n * - **`assignee` omitted** → Defaults to twist owner → Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` → \"Do Someday\" (unscheduled)\n * - `assignee: null` → Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted → defaults to now\n *   // assignee omitted → defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = (\n  | { type: ActivityType.Note; done?: never }\n  | { type: ActivityType.Action; done?: Date | null }\n  | { type: ActivityType.Event; done?: never }\n) &\n  Partial<\n    Omit<\n      ActivityFields,\n      | \"author\"\n      | \"assignee\"\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     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the activity is archived.\n     * - true: Archive the activity\n     * - false: Unarchive the activity\n     * - undefined (default): Preserve current archive state\n     *\n     * Best practice: Set to false during initial syncs to ensure activities\n     * are unarchived. Omit during incremental syncs to preserve user's choice.\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (default): Fall back to legacy behavior (generate from first note with content)\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of a recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * When occurrence matches the recurrence rule but only tags are specified,\n     * the occurrence is created with just tags in activity_tag.occurrence (no activity_exception).\n     *\n     * When any other field is specified, creates/updates an activity_exception row.\n     *\n     * @example\n     * ```typescript\n     * // Create recurring event with per-occurrence RSVPs\n     * const meeting: NewActivity = {\n     *   type: ActivityType.Event,\n     *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n     *   start: new Date(\"2025-01-20T14:00:00Z\"),\n     *   duration: 1800000, // 30 minutes\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [{ email: \"user@example.com\" }] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       start: new Date(\"2025-02-03T15:00:00Z\"), // Reschedule this one\n     *       tags: { [Tag.Attend]: [{ email: \"user@example.com\" }] }\n     *     }\n     *   ]\n     * };\n     * ```\n     */\n    occurrences?: NewActivityOccurrence[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\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      ActivityFields,\n      | \"kind\"\n      | \"start\"\n      | \"end\"\n      | \"title\"\n      | \"assignee\"\n      | \"private\"\n      | \"archived\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n    >\n  > & {\n    /** Update the type of the activity. */\n    type?: ActivityType;\n    /**\n     * Timestamp when the activity was marked as complete. Null if not completed.\n     * Setting done will automatically set the type to Action if not already.\n     */\n    done?: Date | null;\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     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (omitted): Preserve current preview value\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of this recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * Setting a field to null reverts it to the series default.\n     * Omitting a field leaves it unchanged.\n     *\n     * @example\n     * ```typescript\n     * // Update RSVPs for specific occurrences\n     * await plot.updateActivity({\n     *   id: meetingId,\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       tags: { [Tag.Attend]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-10T14:00:00Z\"),\n     *       archived: true  // Cancel this occurrence\n     *     }\n     *   ]\n     * });\n     * ```\n     */\n    occurrences?: (NewActivityOccurrence | ActivityOccurrenceUpdate)[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\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   * Globally unique, stable identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * ⚠️ Ensure IDs are immutable - avoid human-readable slugs or titles.\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  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | 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\" | \"reNote\">\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     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\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 } | { key: string }) &\n  Partial<Pick<Note, \"private\" | \"archived\" | \"content\" | \"links\" | \"reNote\">> & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for privacy compliance\n   * (e.g. Atlassian personal data reporting for GDPR account closure).\n   * Required for contacts sourced from providers that mandate personal data reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
+export default "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with activities, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Activity, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `type: ActivityType`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewActivity, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `type: ActivityType` in NewActivity\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new activity\n * const newActivity: NewActivity = {\n *   type: ActivityType.Action,  // Required\n *   title: \"Review PR\",          // Optional, provided\n *   assignee: null,              // Optional nullable, explicitly clearing\n *   // priority is omitted (undefined), will auto-select or use default\n * };\n *\n * // Updating an activity - only change what's specified\n * const update: ActivityUpdate = {\n *   id: activityId,\n *   done: new Date(),       // Mark as done\n *   assignee: null,         // Clear assignee\n *   // title is omitted, won't be changed\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Kinds of activities. Used only for visual categorization (icon).\n */\nexport enum ActivityKind {\n  document = \"document\", // any external document or item in an external system\n  messages = \"messages\", // emails and chat threads\n  meeting = \"meeting\", // in-person meeting\n  videoconference = \"videoconference\",\n  phone = \"phone\",\n  focus = \"focus\",\n  meal = \"meal\",\n  exercise = \"exercise\",\n  family = \"family\",\n  travel = \"travel\",\n  social = \"social\",\n  entertainment = \"entertainment\",\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  /** File attachment links stored in R2 */\n  file = \"file\",\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 *   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      /** 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      /** File attachment link stored in R2 */\n      type: ActivityLinkType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createActivity({\n *   type: ActivityType.Action,\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  created: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is 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\n/**\n * Common fields shared by all activity types (Note, Action, Event).\n * Does not include the discriminant `type` field or type-specific fields like `done`.\n */\ntype ActivityFields = ActivityCommon & {\n  /**\n   * Globally unique, stable identifier for the item in an external system.\n   * MUST use immutable system-generated IDs, not human-readable slugs or titles.\n   *\n   * Recommended format: `${domain}:${type}:${id}`\n   *\n   * Examples:\n   *   - `linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b` (Linear issue by UUID)\n   *   - `jira:10001:issue:12345` (Jira issue by numeric ID with cloud ID)\n   *   - `gmail:thread:18d4e5f2a3b1c9d7` (Gmail thread by system ID)\n   *\n   * ⚠️ AVOID: URLs with mutable components like team names or issue keys\n   *   - Bad: `https://linear.app/team/issue/TEAM-123/title` (team and title can change)\n   *   - Bad: `jira:issue:PROJECT-42` (issue key can change)\n   *\n   * When set, uniquely identifies the activity within a priority tree for upsert operations.\n   */\n  source: string | null;\n  /** The display title/summary of the activity */\n  title: string;\n  /** Optional kind for additional categorization within the activity */\n  kind: ActivityKind | null;\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   * When marking an activity as done, it becomes an Action; if no assignee is set,\n   * the twist owner is assigned automatically.\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  /**\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  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n  /** Sort order for the activity (fractional positioning) */\n  order: number;\n};\n\nexport type Activity = ActivityFields &\n  (\n    | { type: ActivityType.Note }\n    | {\n        type: ActivityType.Action;\n        /**\n         * Timestamp when the activity was marked as complete. Null if not completed.\n         */\n        done: Date | null;\n      }\n    | { type: ActivityType.Event }\n  );\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Represents a specific instance of a recurring activity.\n * All field values are computed by merging the recurring activity's\n * defaults with any occurrence-specific overrides.\n */\nexport type ActivityOccurrence = {\n  /**\n   * Original date/datetime of this occurrence.\n   * Use start for the occurrence's current start time.\n   * Format: Date object or \"YYYY-MM-DD\" for all-day events.\n   */\n  occurrence: Date | string;\n\n  /**\n   * The recurring activity of which this is an occurrence.\n   */\n  activity: Activity;\n\n  /**\n   * Effective values for this occurrence (series defaults + overrides).\n   * These are the actual values that apply to this specific instance.\n   */\n  start: Date | string;\n  end: Date | string | null;\n  done: Date | null;\n  title: string;\n  /**\n   * Meta is merged, with the occurrence's meta taking precedence.\n   */\n  meta: ActivityMeta | null;\n\n  /**\n   * Tags for this occurrence (merged with the recurring tags).\n   */\n  tags: Tags;\n\n  /**\n   * True if the occurrence is archived.\n   */\n  archived: boolean;\n};\n\n/**\n * Type for creating or updating activity occurrences.\n *\n * Follows the same pattern as Activity/NewActivity:\n * - Required fields: `occurrence` (key) and `start` (for scheduling)\n * - Optional fields: All others from ActivityOccurrence\n * - Additional fields: `twistTags` for add/remove, `unread` for notification control\n *\n * @example\n * ```typescript\n * const activity: NewActivity = {\n *   type: ActivityType.Event,\n *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n *   occurrences: [\n *     {\n *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n *       start: new Date(\"2025-01-27T14:00:00Z\"),\n *       tags: { [Tag.Skip]: [user] }\n *     }\n *   ]\n * };\n * ```\n */\nexport type NewActivityOccurrence = Pick<\n  ActivityOccurrence,\n  \"occurrence\" | \"start\"\n> &\n  Partial<\n    Omit<ActivityOccurrence, \"occurrence\" | \"start\" | \"activity\" | \"tags\">\n  > & {\n    /**\n     * Tags specific to this occurrence.\n     * These replace any recurrence-level tags for this occurrence.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags on this occurrence.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Whether this occurrence should be marked as unread for users.\n     * - undefined/omitted (default): Occurrence is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Occurrence is explicitly unread for ALL users (use sparingly)\n     * - false: Occurrence is marked as read for all users\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n  };\n\n/**\n * Inline type for creating/updating occurrences within NewActivity/ActivityUpdate.\n * Used to specify occurrence-specific overrides when creating or updating a recurring activity.\n */\nexport type ActivityOccurrenceUpdate = Pick<\n  NewActivityOccurrence,\n  \"occurrence\"\n> &\n  Partial<Omit<NewActivityOccurrence, \"occurrence\" | \"activity\">>;\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Defaults for Actions**\n *\n * When creating an Activity of type `Action`:\n * - **`start` omitted** → Defaults to current time (now) → \"Do Now\"\n * - **`assignee` omitted** → Defaults to twist owner → Assigned action\n *\n * To create unassigned backlog items (common for synced tasks), you MUST explicitly set BOTH:\n * - `start: null` → \"Do Someday\" (unscheduled)\n * - `assignee: null` → Unassigned\n *\n * **Scheduling States**:\n * - **\"Do Now\"** (actionable today): Omit `start` or set to current time\n * - **\"Do Later\"** (scheduled): Set `start` to a future Date\n * - **\"Do Someday\"** (backlog): Set `start: null`\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Assigned to twist owner, actionable immediately\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // start omitted → defaults to now\n *   // assignee omitted → defaults to twist owner\n * };\n *\n * // \"Do Someday\" - UNASSIGNED backlog item (for synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null,      // Must explicitly set to null\n *   assignee: null    // Must explicitly set to null\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = (\n  | { type: ActivityType.Note; done?: never }\n  | { type: ActivityType.Action; done?: Date | null }\n  | { type: ActivityType.Event; done?: never }\n) &\n  Partial<\n    Omit<\n      ActivityFields,\n      \"author\" | \"assignee\" | \"priority\" | \"tags\" | \"mentions\" | \"id\" | \"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     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the activity is archived.\n     * - true: Archive the activity\n     * - false: Unarchive the activity\n     * - undefined (default): Preserve current archive state\n     *\n     * Best practice: Set to false during initial syncs to ensure activities\n     * are unarchived. Omit during incremental syncs to preserve user's choice.\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (default): Fall back to legacy behavior (generate from first note with content)\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of a recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * When occurrence matches the recurrence rule but only tags are specified,\n     * the occurrence is created with just tags in activity_tag.occurrence (no activity_exception).\n     *\n     * When any other field is specified, creates/updates an activity_exception row.\n     *\n     * @example\n     * ```typescript\n     * // Create recurring event with per-occurrence RSVPs\n     * const meeting: NewActivity = {\n     *   type: ActivityType.Event,\n     *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n     *   start: new Date(\"2025-01-20T14:00:00Z\"),\n     *   duration: 1800000, // 30 minutes\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [{ email: \"user@example.com\" }] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       start: new Date(\"2025-02-03T15:00:00Z\"), // Reschedule this one\n     *       tags: { [Tag.Attend]: [{ email: \"user@example.com\" }] }\n     *     }\n     *   ]\n     * };\n     * ```\n     */\n    occurrences?: NewActivityOccurrence[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\n  };\n\nexport type ActivityFilter = {\n  type?: ActorType;\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many activities are included.\n */\ntype ActivityBulkUpdateFields = Partial<\n  Pick<ActivityFields, \"kind\" | \"title\" | \"private\" | \"archived\" | \"meta\" | \"order\">\n> & {\n  /** Update the type of all matching activities. */\n  type?: ActivityType;\n  /**\n   * Timestamp when the activities were marked as complete. Null to clear.\n   * Setting done will automatically set the type to Action if not already.\n   */\n  done?: Date | null;\n};\n\n/**\n * Fields supported by single-activity updates via `id` or `source`.\n * Includes all bulk fields plus scheduling, recurrence, tags, and occurrences.\n */\ntype ActivitySingleUpdateFields = ActivityBulkUpdateFields &\n  Partial<\n    Pick<\n      ActivityFields,\n      | \"start\"\n      | \"end\"\n      | \"assignee\"\n      | \"recurrenceRule\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\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     * Optional preview content for the activity. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     *\n     * - string: Use this content for preview generation\n     * - null: Explicitly disable preview (no preview will be shown)\n     * - undefined (omitted): Preserve current preview value\n     *\n     * This field is write-only and won't be returned when reading activities.\n     */\n    preview?: string | null;\n\n    /**\n     * Create or update specific occurrences of this recurring activity.\n     * Each entry specifies overrides for a specific occurrence.\n     *\n     * Setting a field to null reverts it to the series default.\n     * Omitting a field leaves it unchanged.\n     *\n     * @example\n     * ```typescript\n     * // Update RSVPs for specific occurrences\n     * await plot.updateActivity({\n     *   id: meetingId,\n     *   occurrences: [\n     *     {\n     *       occurrence: new Date(\"2025-01-27T14:00:00Z\"),\n     *       tags: { [Tag.Skip]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-03T14:00:00Z\"),\n     *       tags: { [Tag.Attend]: [user] }\n     *     },\n     *     {\n     *       occurrence: new Date(\"2025-02-10T14:00:00Z\"),\n     *       archived: true  // Cancel this occurrence\n     *     }\n     *   ]\n     * });\n     * ```\n     */\n    occurrences?: (NewActivityOccurrence | ActivityOccurrenceUpdate)[];\n\n    /**\n     * Dates to add to the recurrence exclusion list.\n     * These are merged with existing exdates. Use this for incremental updates\n     * (e.g., cancelling a single occurrence) instead of replacing the full list.\n     */\n    addRecurrenceExdates?: Date[];\n\n    /**\n     * Dates to remove from the recurrence exclusion list.\n     * Use this to \"uncancel\" a previously excluded occurrence.\n     */\n    removeRecurrenceExdates?: Date[];\n  };\n\nexport type ActivityUpdate =\n  | (({ id: Uuid } | { source: string }) & ActivitySingleUpdateFields)\n  | ({\n      /**\n       * Update all activities matching the specified criteria. Only activities\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ActivityFilter;\n    } & ActivityBulkUpdateFields);\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   * Globally unique, stable identifier for the note within its activity.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * ⚠️ Ensure IDs are immutable - avoid human-readable slugs or titles.\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  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | 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<\n    Note,\n    \"author\" | \"activity\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\"\n  >\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     * - undefined/omitted (default): Activity is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Activity is explicitly unread for ALL users (use sparingly)\n     * - false: Activity is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\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 } | { key: string }) &\n  Partial<\n    Pick<Note, \"private\" | \"archived\" | \"content\" | \"links\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for privacy compliance\n   * (e.g. Atlassian personal data reporting for GDPR account closure).\n   * Required for contacts sourced from providers that mandate personal data reporting.\n   */\n  source?: { provider: AuthProvider; accountId: 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,i7zCAAi7zC,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,wn1CAAwn1C,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 Actor, type Priority } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\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<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // \u2705 undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // \u2705 Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // \u2705 Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this 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 with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\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   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(\"processBatch\", { page: 1 });\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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 {\n  type Actor,\n  type ActivityFilter,\n  type NewActivityWithNotes,\n  type Priority,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Options for tools that sync activities from external services.\n *\n * @example\n * ```typescript\n * static readonly Options: SyncToolOptions;\n * ```\n */\nexport type SyncToolOptions = {\n  /** Callback invoked for each synced item. The tool adds sync metadata before passing it. */\n  onItem: (item: NewActivityWithNotes) => Promise<void>;\n  /** Callback invoked when a syncable is disabled, receiving an ActivityFilter for bulk operations. */\n  onSyncableDisabled?: (filter: ActivityFilter) => Promise<void>;\n};\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<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // \u2705 undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // \u2705 Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // \u2705 Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Lists all storage keys matching a prefix.\n   *\n   * @param prefix - The prefix to match keys against\n   * @returns Promise resolving to an array of matching key strings\n   */\n  protected async list(prefix: string): Promise<string[]> {\n    return this.tools.store.list(prefix);\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 with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\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   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(\"processBatch\", { page: 1 });\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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,g4XAAk2X;AAAj3X,wBAAk3X"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,gwZAAkuZ;AAAjvZ,wBAAkvZ"}

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 Actor, type Priority } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\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<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ✅ Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // ✅ Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this 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 with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\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   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(\"processBatch\", { page: 1 });\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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 {\n  type Actor,\n  type ActivityFilter,\n  type NewActivityWithNotes,\n  type Priority,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Options for tools that sync activities from external services.\n *\n * @example\n * ```typescript\n * static readonly Options: SyncToolOptions;\n * ```\n */\nexport type SyncToolOptions = {\n  /** Callback invoked for each synced item. The tool adds sync metadata before passing it. */\n  onItem: (item: NewActivityWithNotes) => Promise<void>;\n  /** Callback invoked when a syncable is disabled, receiving an ActivityFilter for bulk operations. */\n  onSyncableDisabled?: (filter: ActivityFilter) => Promise<void>;\n};\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<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ✅ Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // ✅ Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Lists all storage keys matching a prefix.\n   *\n   * @param prefix - The prefix to match keys against\n   * @returns Promise resolving to an array of matching key strings\n   */\n  protected async list(prefix: string): Promise<string[]> {\n    return this.tools.store.list(prefix);\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 with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\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   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(\"processBatch\", { page: 1 });\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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   * @param context - Optional context containing the actor who triggered activation\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, context?: { actor: Actor }): 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,k2XAAk2X,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,kuZAAkuZ,CAAC"}

package/dist/llm-docs/tools/integrations.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 Actor, type ActorId, type ActivityLink, ITool, Serializable } from \"..\";\n\n/**\n * Built-in tool for managing OAuth authentication flows.\n *\n * The Integrations tool provides a unified interface for requesting user authorization\n * from external service providers like Google and Microsoft. It handles the\n * OAuth flow creation, token management, and callback integration.\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool {\n *   private auth: Integrations;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.integrations = tools.get(Integrations);\n *   }\n *\n *   async requestAuth() {\n *     return await this.integrations.request({\n *       provider: AuthProvider.Google,\n *       scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"]\n *     }, {\n *       functionName: \"onAuthComplete\",\n *       context: { provider: \"google\" }\n *     });\n *   }\n *\n *   async onAuthComplete(authResult: Authorization, context: any) {\n *     const authToken = await this.integrations.get(authResult.provider, authResult.actor.id);\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Initiates an OAuth authentication flow.\n   *\n   * Creates an authentication link that users can click to authorize access\n   * to the specified provider with the requested scopes. When authorization\n   * completes, the callback will be invoked with the Authorization and any extraArgs.\n   *\n   * @param auth - Authentication configuration\n   * @param auth.provider - The OAuth provider to authenticate with\n   * @param auth.scopes - Array of OAuth scopes to request\n   * @param callback - Function receiving (authorization, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, must be serializable)\n   * @returns Promise resolving to an ActivityLink for the auth flow\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract request<\n    TArgs extends Serializable[],\n    TCallback extends (auth: Authorization, ...args: TArgs) => any\n  >(\n    auth: {\n      provider: AuthProvider;\n      scopes: string[];\n    },\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves an access token (refreshing it first if necessary).\n   *\n   * Looks up the token by provider and actor ID. If the given actor hasn't\n   * directly authenticated but is linked (same user_id) to a contact that has,\n   * returns that linked contact's token.\n   *\n   * Returns null if no valid token is found.\n   *\n   * @param provider - The OAuth provider to retrieve a token for\n   * @param actorId - The actor (contact) ID to look up\n   * @returns Promise resolving to the access token or null if no longer available\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, actorId: ActorId): Promise<AuthToken | null>;\n}\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+declare const _default: "import { type Actor, type ActorId, ITool, Serializable } from \"..\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getSyncables() and managed by users in the twist setup/edit modal.\n */\nexport type Syncable = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested syncable resources (e.g., subfolders) */\n  children?: Syncable[];\n};\n\n/**\n * Configuration for an OAuth provider in a tool's build options.\n * Declares the provider, scopes, and lifecycle callbacks.\n */\nexport type IntegrationProviderConfig = {\n  /** The OAuth provider */\n  provider: AuthProvider;\n  /** OAuth scopes to request */\n  scopes: string[];\n  /** Returns available syncables for the authorized actor. Must not use Plot tool. */\n  getSyncables: (auth: Authorization, token: AuthToken) => Promise<Syncable[]>;\n  /** Called when a syncable resource is enabled for syncing */\n  onSyncEnabled: (syncable: Syncable) => Promise<void>;\n  /** Called when a syncable resource is disabled */\n  onSyncDisabled: (syncable: Syncable) => Promise<void>;\n};\n\n/**\n * Options passed to Integrations in the build() method.\n */\nexport type IntegrationOptions = {\n  /** Provider configurations with lifecycle callbacks */\n  providers: IntegrationProviderConfig[];\n};\n\n/**\n * Built-in tool for managing OAuth authentication and syncable resources.\n *\n * The redesigned Integrations tool:\n * 1. Declares providers/scopes in build options with lifecycle callbacks\n * 2. Manages syncable resources (calendars, projects, etc.) per actor\n * 3. Returns tokens for the user who enabled sync on a syncable\n * 4. Supports per-actor auth via actAs() for write-back operations\n *\n * Auth and syncable management is handled in the twist edit modal in Flutter,\n * removing the need for tools to create auth activities or selection UIs.\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   static readonly PROVIDER = AuthProvider.Google;\n *   static readonly SCOPES = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations, {\n *         providers: [{\n *           provider: AuthProvider.Google,\n *           scopes: CalendarTool.SCOPES,\n *           getSyncables: this.getSyncables,\n *           onSyncEnabled: this.onSyncEnabled,\n *           onSyncDisabled: this.onSyncDisabled,\n *         }]\n *       }),\n *     };\n *   }\n *\n *   async getSyncables(auth: Authorization, token: AuthToken): Promise<Syncable[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a syncable resource.\n   *\n   * Returns the token of the user who enabled sync on the given syncable.\n   * If the syncable is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param provider - The OAuth provider\n   * @param syncableId - The syncable resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, syncableId: string): Promise<AuthToken | null>;\n\n  /**\n   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n}\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
 export default _default;
 //# sourceMappingURL=integrations.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,snKAAsnK;AAAroK,wBAAsoK"}
+{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,o2NAAo2N;AAAn3N,wBAAo3N"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { type Actor, type ActorId, type ActivityLink, ITool, Serializable } from \"..\";\n\n/**\n * Built-in tool for managing OAuth authentication flows.\n *\n * The Integrations tool provides a unified interface for requesting user authorization\n * from external service providers like Google and Microsoft. It handles the\n * OAuth flow creation, token management, and callback integration.\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool {\n *   private auth: Integrations;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.integrations = tools.get(Integrations);\n *   }\n *\n *   async requestAuth() {\n *     return await this.integrations.request({\n *       provider: AuthProvider.Google,\n *       scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"]\n *     }, {\n *       functionName: \"onAuthComplete\",\n *       context: { provider: \"google\" }\n *     });\n *   }\n *\n *   async onAuthComplete(authResult: Authorization, context: any) {\n *     const authToken = await this.integrations.get(authResult.provider, authResult.actor.id);\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Initiates an OAuth authentication flow.\n   *\n   * Creates an authentication link that users can click to authorize access\n   * to the specified provider with the requested scopes. When authorization\n   * completes, the callback will be invoked with the Authorization and any extraArgs.\n   *\n   * @param auth - Authentication configuration\n   * @param auth.provider - The OAuth provider to authenticate with\n   * @param auth.scopes - Array of OAuth scopes to request\n   * @param callback - Function receiving (authorization, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, must be serializable)\n   * @returns Promise resolving to an ActivityLink for the auth flow\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract request<\n    TArgs extends Serializable[],\n    TCallback extends (auth: Authorization, ...args: TArgs) => any\n  >(\n    auth: {\n      provider: AuthProvider;\n      scopes: string[];\n    },\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves an access token (refreshing it first if necessary).\n   *\n   * Looks up the token by provider and actor ID. If the given actor hasn't\n   * directly authenticated but is linked (same user_id) to a contact that has,\n   * returns that linked contact's token.\n   *\n   * Returns null if no valid token is found.\n   *\n   * @param provider - The OAuth provider to retrieve a token for\n   * @param actorId - The actor (contact) ID to look up\n   * @returns Promise resolving to the access token or null if no longer available\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, actorId: ActorId): Promise<AuthToken | null>;\n}\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+export default "import { type Actor, type ActorId, ITool, Serializable } from \"..\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getSyncables() and managed by users in the twist setup/edit modal.\n */\nexport type Syncable = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested syncable resources (e.g., subfolders) */\n  children?: Syncable[];\n};\n\n/**\n * Configuration for an OAuth provider in a tool's build options.\n * Declares the provider, scopes, and lifecycle callbacks.\n */\nexport type IntegrationProviderConfig = {\n  /** The OAuth provider */\n  provider: AuthProvider;\n  /** OAuth scopes to request */\n  scopes: string[];\n  /** Returns available syncables for the authorized actor. Must not use Plot tool. */\n  getSyncables: (auth: Authorization, token: AuthToken) => Promise<Syncable[]>;\n  /** Called when a syncable resource is enabled for syncing */\n  onSyncEnabled: (syncable: Syncable) => Promise<void>;\n  /** Called when a syncable resource is disabled */\n  onSyncDisabled: (syncable: Syncable) => Promise<void>;\n};\n\n/**\n * Options passed to Integrations in the build() method.\n */\nexport type IntegrationOptions = {\n  /** Provider configurations with lifecycle callbacks */\n  providers: IntegrationProviderConfig[];\n};\n\n/**\n * Built-in tool for managing OAuth authentication and syncable resources.\n *\n * The redesigned Integrations tool:\n * 1. Declares providers/scopes in build options with lifecycle callbacks\n * 2. Manages syncable resources (calendars, projects, etc.) per actor\n * 3. Returns tokens for the user who enabled sync on a syncable\n * 4. Supports per-actor auth via actAs() for write-back operations\n *\n * Auth and syncable management is handled in the twist edit modal in Flutter,\n * removing the need for tools to create auth activities or selection UIs.\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   static readonly PROVIDER = AuthProvider.Google;\n *   static readonly SCOPES = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations, {\n *         providers: [{\n *           provider: AuthProvider.Google,\n *           scopes: CalendarTool.SCOPES,\n *           getSyncables: this.getSyncables,\n *           onSyncEnabled: this.onSyncEnabled,\n *           onSyncDisabled: this.onSyncDisabled,\n *         }]\n *       }),\n *     };\n *   }\n *\n *   async getSyncables(auth: Authorization, token: AuthToken): Promise<Syncable[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a syncable resource.\n   *\n   * Returns the token of the user who enabled sync on the given syncable.\n   * If the syncable is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param provider - The OAuth provider\n   * @param syncableId - The syncable resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, syncableId: string): Promise<AuthToken | null>;\n\n  /**\n   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n}\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
 //# sourceMappingURL=integrations.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"integrations.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,snKAAsnK,CAAC"}
+{"version":3,"file":"integrations.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,o2NAAo2N,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 ActivityOccurrence,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  type Tag,\n  Uuid,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       activity: {\n   *         access: ActivityAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       activity: {\n   *         access: ActivityAccess.Create,\n   *         updated: this.onActivityUpdated\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *         created: this.onNoteCreated\n   *       },\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n          /**\n           * If present, this update is for a specific occurrence of a recurring activity.\n           */\n          occurrence?: ActivityOccurrence;\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 created activity's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Uuid>;\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 activity IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * **Important**: This method only updates existing activities. It will throw an error\n   * if the activity does not exist. Use `createActivity()` to create or update (upsert)\n   * activities.\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 or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the activity does not exist\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 created note's ID\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<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     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<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves an activity by ID or source.\n   *\n   * This method enables lookup of activities either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived activities\n   * are included in the results.\n   *\n   * @param activity - Activity lookup by ID or source\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivity(\n    activity: { id: Uuid } | { source: string }\n  ): Promise<Activity | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the activity). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
+declare const _default: "import {\n  type Activity,\n  type ActivityOccurrence,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  type Tag,\n  Uuid,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       activity: {\n   *         access: ActivityAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       activity: {\n   *         access: ActivityAccess.Create,\n   *         updated: this.onActivityUpdated\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *         created: this.onNoteCreated\n   *       },\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n          /**\n           * If present, this update is for a specific occurrence of a recurring activity.\n           */\n          occurrence?: ActivityOccurrence;\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 created activity's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Uuid>;\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 activity IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * **Important**: This method only updates existing activities. It will throw an error\n   * if the activity does not exist. Use `createActivity()` to create or update (upsert)\n   * activities.\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 or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the activity does not exist\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 created note's ID\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<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     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<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves an activity by ID or source.\n   *\n   * This method enables lookup of activities either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived activities\n   * are included in the results.\n   *\n   * @param activity - Activity lookup by ID or source\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivity(\n    activity: { id: Uuid } | { source: string }\n  ): Promise<Activity | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the activity). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with 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,w0gBAAw0gB;AAAv1gB,wBAAw1gB"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,+1gBAA+1gB;AAA92gB,wBAA+2gB"}