@plotday/twister 0.26.0 → 0.28.0

package/dist/llm-docs/common/messaging.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import type { ActivityLink, NewActivityWithNotes } from \"../index\";\n\n/**\n * Represents a successful messaging service authorization.\n *\n * Returned by messaging tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * messaging operations.\n */\nexport type MessagingAuth = {\n  /** Opaque token for messaging operations */\n  authToken: string;\n};\n\n/**\n * Represents a channel from an external messaging service.\n *\n * Contains metadata about a specific channel that can be synced\n * with Plot.\n */\nexport interface MessageChannel {\n  /** Unique identifier for the channel within the provider */\n  id: string;\n  /** Human-readable name of the channel (e.g., \"Inbox\", \"#general\", \"My Team Thread\") */\n  name: string;\n  /** Optional description or additional details about the channel */\n  description: string | null;\n  /** Whether this is the user's primary/default channel (e.g. email inbox) */\n  primary: boolean;\n}\n\n/**\n * Configuration options for messaging synchronization.\n *\n * Controls the time range and other parameters for messaging sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport interface MessageSyncOptions {\n  /** Earliest date to sync events from (inclusive) */\n  timeMin?: Date;\n}\n\n/**\n * Base interface for email and chat integration tools.\n *\n * All synced messages/emails are converted to ActivityWithNotes objects.\n * Each email thread or chat conversation becomes an Activity with Notes for each message.\n */\nexport interface MessagingTool {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<TCallback extends (auth: MessagingAuth, ...args: any[]) => any>(\n    callback: TCallback,\n    ...extraArgs: TCallback extends (auth: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of conversation channels (inboxes, channels) accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available conversation channels\n   */\n  getChannels(authToken: string): Promise<MessageChannel[]>;\n\n  /**\n   * Begins synchronizing messages from a specific channel.\n   *\n   * Email threads and chat conversations are converted to ActivityWithNotes objects.\n   * Each object contains an Activity (with subject/title) and Notes array (one per message).\n   * The Activity.id can be used as a stable conversation identifier.\n   *\n   * @param authToken - Authorization token for access\n   * @param channelId - ID of the channel (e.g., channel, inbox) to sync\n   * @param callback - Function receiving (thread, ...extraArgs) for each synced conversation\n   * @param options - Optional configuration for limiting the sync scope (e.g., time range)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TCallback extends (thread: NewActivityWithNotes, ...args: any[]) => any\n  >(\n    authToken: string,\n    channelId: string,\n    callback: TCallback,\n    options?: MessageSyncOptions,\n    ...extraArgs: TCallback extends (thread: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing messages from a specific channel.\n   *\n   * @param authToken - Authorization token for access\n   * @param channelId - ID of the channel to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, channelId: string): Promise<void>;\n}\n";
+export default "import type { ActivityLink, NewActivityWithNotes, SyncUpdate } from \"../index\";\n\n/**\n * Represents a successful messaging service authorization.\n *\n * Returned by messaging tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * messaging operations.\n */\nexport type MessagingAuth = {\n  /** Opaque token for messaging operations */\n  authToken: string;\n};\n\n/**\n * Represents a channel from an external messaging service.\n *\n * Contains metadata about a specific channel that can be synced\n * with Plot.\n */\nexport interface MessageChannel {\n  /** Unique identifier for the channel within the provider */\n  id: string;\n  /** Human-readable name of the channel (e.g., \"Inbox\", \"#general\", \"My Team Thread\") */\n  name: string;\n  /** Optional description or additional details about the channel */\n  description: string | null;\n  /** Whether this is the user's primary/default channel (e.g. email inbox) */\n  primary: boolean;\n}\n\n/**\n * Configuration options for messaging synchronization.\n *\n * Controls the time range and other parameters for messaging sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport interface MessageSyncOptions {\n  /** Earliest date to sync events from (inclusive) */\n  timeMin?: Date;\n}\n\n/**\n * Base interface for email and chat integration tools.\n *\n * All synced messages/emails are converted to ActivityWithNotes objects.\n * Each email thread or chat conversation becomes an Activity with Notes for each message.\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (thread URL or ID) and Note.key (message ID) for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport interface MessagingTool {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<TCallback extends (auth: MessagingAuth, ...args: any[]) => any>(\n    callback: TCallback,\n    ...extraArgs: TCallback extends (auth: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of conversation channels (inboxes, channels) accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available conversation channels\n   */\n  getChannels(authToken: string): Promise<MessageChannel[]>;\n\n  /**\n   * Begins synchronizing messages from a specific channel.\n   *\n   * Email threads and chat conversations are converted to SyncUpdate objects,\n   * which can be either new items or updates to existing items.\n   *\n   * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):\n   * - Set Activity.source to the thread/conversation URL or stable ID (e.g., \"slack:{channelId}:{threadTs}\")\n   * - Use Note.key for individual messages (e.g., \"message-{messageId}\")\n   * - Each message becomes a separate note with unique key for upserts\n   * - No manual ID tracking needed - Plot handles deduplication automatically\n   * - Send NewActivityWithNotes for all threads (creates new or updates existing)\n   * - Set activity.unread = false for initial sync, true for incremental updates\n   *\n   * **Alternative** (Strategy 3 - Advanced cases):\n   * - Use Uuid.Generate() and store ID mappings when creating multiple activities per thread\n   * - See SYNC_STRATEGIES.md for when this is appropriate\n   *\n   * @param authToken - Authorization token for access\n   * @param channelId - ID of the channel (e.g., channel, inbox) to sync\n   * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced conversation\n   * @param options - Optional configuration for limiting the sync scope (e.g., time range)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any\n  >(\n    authToken: string,\n    channelId: string,\n    callback: TCallback,\n    options?: MessageSyncOptions,\n    ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing messages from a specific channel.\n   *\n   * @param authToken - Authorization token for access\n   * @param channelId - ID of the channel to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, channelId: string): Promise<void>;\n}\n";
 //# sourceMappingURL=messaging.js.map

package/dist/llm-docs/common/messaging.js.map

@@ -1 +1 @@
-{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../../src/llm-docs/common/messaging.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,23HAA23H,CAAC"}
+{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../../src/llm-docs/common/messaging.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,6vJAA6vJ,CAAC"}

package/dist/llm-docs/common/projects.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 {\n  ActivityLink,\n  ActivityUpdate,\n  NewActivityWithNotes,\n} from \"../index\";\n\n/**\n * Represents a successful project management service authorization.\n *\n * Returned by project management tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * project operations.\n */\nexport type ProjectAuth = {\n  /** Opaque token for project management operations */\n  authToken: string;\n};\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot.\n */\nexport interface Project {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n}\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport interface ProjectSyncOptions {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n}\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n */\nexport interface ProjectTool {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<TCallback extends (auth: ProjectAuth, ...args: any[]) => any>(\n    callback: TCallback,\n    ...extraArgs: TCallback extends (auth: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(authToken: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Issues and tasks are converted to ActivityWithNotes objects.\n   * Each object contains an Activity (with issue title and metadata) and Notes array\n   * (description as first note, followed by comments).\n   * The Activity.source should be set for deduplication.\n   *\n   * When an issue is updated, tools should check for existing Activity using\n   * getActivityBySource() and add a Note rather than creating a new Activity.\n   *\n   * Tools implementing this should set issue.unread based on sync type:\n   * - Initial sync (historical data): Set issue.unread = false\n   * - Incremental updates (webhooks): Set issue.unread = true or leave undefined\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to sync\n   * @param callback - Function receiving (issue, ...extraArgs) for each synced issue.\n   *                   The issue.unread field indicates whether this is from initial sync.\n   * @param options - Optional configuration for limiting the sync scope (e.g., time range)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TCallback extends (\n      issue: NewActivityWithNotes,\n      ...args: any[]\n    ) => any\n  >(\n    authToken: string,\n    projectId: string,\n    callback: TCallback,\n    options?: ProjectSyncOptions,\n    ...extraArgs: TCallback extends (\n      issue: any,\n      ...rest: infer R\n    ) => any\n      ? R\n      : []\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * The update object contains only the fields that changed, plus id and source.\n   * Uses the combination of start and doneAt to determine workflow state:\n   * - doneAt set \u2192 Completed/Done state\n   * - doneAt null + start set \u2192 In Progress/Active state\n   * - doneAt null + start null \u2192 Backlog/Todo state\n   *\n   * @param authToken - Authorization token for access\n   * @param update - ActivityUpdate with changed fields (includes id and source)\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(authToken: string, update: ActivityUpdate): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * @param authToken - Authorization token for access\n   * @param issueId - ID or key of the issue/task to comment on\n   * @param body - The comment text content\n   * @returns Promise that resolves when the comment is added\n   */\n  addIssueComment?(\n    authToken: string,\n    issueId: string,\n    body: string\n  ): Promise<void>;\n}\n";
+declare const _default: "import type {\n  ActivityLink,\n  ActivityUpdate,\n  NewActivityWithNotes,\n  SyncUpdate,\n} from \"../index\";\n\n/**\n * Represents a successful project management service authorization.\n *\n * Returned by project management tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * project operations.\n */\nexport type ProjectAuth = {\n  /** Opaque token for project management operations */\n  authToken: string;\n};\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot.\n */\nexport interface Project {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n}\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport interface ProjectSyncOptions {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n}\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (issue URL) and Note.key for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport interface ProjectTool {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<TCallback extends (auth: ProjectAuth, ...args: any[]) => any>(\n    callback: TCallback,\n    ...extraArgs: TCallback extends (auth: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(authToken: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Issues and tasks are converted to SyncUpdate objects, which can be either\n   * new items or updates to existing items.\n   *\n   * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):\n   * - Set Activity.source to the issue's canonical URL (e.g., Linear issue URL, Jira issue URL)\n   * - Use Note.key for issue details:\n   *   - key: \"description\" for issue description (upserts on changes)\n   *   - key: \"metadata\" for status, priority, assignee, etc.\n   *   - key: \"comment-{commentId}\" for individual comments (unique per comment)\n   * - No manual ID tracking needed - Plot handles deduplication automatically\n   * - Send NewActivityWithNotes for all issues (creates new or updates existing)\n   * - Set activity.unread = false for initial sync, true for incremental updates\n   *\n   * **Alternative** (Strategy 3 - Advanced cases):\n   * - Use Uuid.Generate() and store ID mappings when creating multiple activities per issue\n   * - See SYNC_STRATEGIES.md for when this is appropriate\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to sync\n   * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced issue\n   * @param options - Optional configuration for limiting the sync scope (e.g., time range)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TCallback extends (\n      syncUpdate: SyncUpdate,\n      ...args: any[]\n    ) => any\n  >(\n    authToken: string,\n    projectId: string,\n    callback: TCallback,\n    options?: ProjectSyncOptions,\n    ...extraArgs: TCallback extends (\n      syncUpdate: any,\n      ...rest: infer R\n    ) => any\n      ? R\n      : []\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * The update object contains only the fields that changed, plus id and source.\n   * Uses the combination of start and done to determine workflow state:\n   * - done set \u2192 Completed/Done state\n   * - done null + start set \u2192 In Progress/Active state\n   * - done null + start null \u2192 Backlog/Todo state\n   *\n   * @param authToken - Authorization token for access\n   * @param update - ActivityUpdate with changed fields (includes id and source)\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(authToken: string, update: ActivityUpdate): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * @param authToken - Authorization token for access\n   * @param issueId - ID or key of the issue/task to comment on\n   * @param body - The comment text content\n   * @returns Promise that resolves when the comment is added\n   */\n  addIssueComment?(\n    authToken: string,\n    issueId: string,\n    body: string\n  ): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=projects.d.ts.map

package/dist/llm-docs/common/projects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,stLAAusL;AAAttL,wBAAutL"}
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,upMAAwoM;AAAvpM,wBAAwpM"}

package/dist/llm-docs/common/projects.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import type {\n  ActivityLink,\n  ActivityUpdate,\n  NewActivityWithNotes,\n} from \"../index\";\n\n/**\n * Represents a successful project management service authorization.\n *\n * Returned by project management tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * project operations.\n */\nexport type ProjectAuth = {\n  /** Opaque token for project management operations */\n  authToken: string;\n};\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot.\n */\nexport interface Project {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n}\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport interface ProjectSyncOptions {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n}\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n */\nexport interface ProjectTool {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<TCallback extends (auth: ProjectAuth, ...args: any[]) => any>(\n    callback: TCallback,\n    ...extraArgs: TCallback extends (auth: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(authToken: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Issues and tasks are converted to ActivityWithNotes objects.\n   * Each object contains an Activity (with issue title and metadata) and Notes array\n   * (description as first note, followed by comments).\n   * The Activity.source should be set for deduplication.\n   *\n   * When an issue is updated, tools should check for existing Activity using\n   * getActivityBySource() and add a Note rather than creating a new Activity.\n   *\n   * Tools implementing this should set issue.unread based on sync type:\n   * - Initial sync (historical data): Set issue.unread = false\n   * - Incremental updates (webhooks): Set issue.unread = true or leave undefined\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to sync\n   * @param callback - Function receiving (issue, ...extraArgs) for each synced issue.\n   *                   The issue.unread field indicates whether this is from initial sync.\n   * @param options - Optional configuration for limiting the sync scope (e.g., time range)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TCallback extends (\n      issue: NewActivityWithNotes,\n      ...args: any[]\n    ) => any\n  >(\n    authToken: string,\n    projectId: string,\n    callback: TCallback,\n    options?: ProjectSyncOptions,\n    ...extraArgs: TCallback extends (\n      issue: any,\n      ...rest: infer R\n    ) => any\n      ? R\n      : []\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * The update object contains only the fields that changed, plus id and source.\n   * Uses the combination of start and doneAt to determine workflow state:\n   * - doneAt set → Completed/Done state\n   * - doneAt null + start set → In Progress/Active state\n   * - doneAt null + start null → Backlog/Todo state\n   *\n   * @param authToken - Authorization token for access\n   * @param update - ActivityUpdate with changed fields (includes id and source)\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(authToken: string, update: ActivityUpdate): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * @param authToken - Authorization token for access\n   * @param issueId - ID or key of the issue/task to comment on\n   * @param body - The comment text content\n   * @returns Promise that resolves when the comment is added\n   */\n  addIssueComment?(\n    authToken: string,\n    issueId: string,\n    body: string\n  ): Promise<void>;\n}\n";
+export default "import type {\n  ActivityLink,\n  ActivityUpdate,\n  NewActivityWithNotes,\n  SyncUpdate,\n} from \"../index\";\n\n/**\n * Represents a successful project management service authorization.\n *\n * Returned by project management tools when authorization completes successfully.\n * The auth token is an opaque identifier that can be used for subsequent\n * project operations.\n */\nexport type ProjectAuth = {\n  /** Opaque token for project management operations */\n  authToken: string;\n};\n\n/**\n * Represents a project from an external project management service.\n *\n * Contains metadata about a specific project/board/workspace that can be synced\n * with Plot.\n */\nexport interface Project {\n  /** Unique identifier for the project within the provider */\n  id: string;\n  /** Human-readable name of the project (e.g., \"Q1 Roadmap\", \"Engineering\") */\n  name: string;\n  /** Optional description or additional details about the project */\n  description: string | null;\n  /** Optional project key/abbreviation (e.g., \"PROJ\" in Jira, \"ENG\" in Linear) */\n  key: string | null;\n}\n\n/**\n * Configuration options for project synchronization.\n *\n * Controls the time range and other parameters for project sync operations.\n * Used to limit sync scope and optimize performance.\n */\nexport interface ProjectSyncOptions {\n  /** Earliest date to sync issues from (inclusive) */\n  timeMin?: Date;\n}\n\n/**\n * Base interface for project management integration tools.\n *\n * All synced issues/tasks are converted to ActivityWithNotes objects.\n * Each issue becomes an Activity with Notes for the description and comments.\n *\n * **Recommended Data Sync Strategy:**\n * Use Activity.source (issue URL) and Note.key for automatic upserts.\n * See SYNC_STRATEGIES.md for detailed patterns.\n */\nexport interface ProjectTool {\n  /**\n   * Initiates the authorization flow for the service.\n   *\n   * @param callback - Function receiving (auth, ...extraArgs) when auth completes\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise resolving to an ActivityLink to initiate the auth flow\n   */\n  requestAuth<TCallback extends (auth: ProjectAuth, ...args: any[]) => any>(\n    callback: TCallback,\n    ...extraArgs: TCallback extends (auth: any, ...rest: infer R) => any\n      ? R\n      : []\n  ): Promise<ActivityLink>;\n\n  /**\n   * Retrieves the list of projects accessible to the user.\n   *\n   * @param authToken - Authorization token from successful auth flow\n   * @returns Promise resolving to array of available projects\n   */\n  getProjects(authToken: string): Promise<Project[]>;\n\n  /**\n   * Begins synchronizing issues from a specific project.\n   *\n   * Issues and tasks are converted to SyncUpdate objects, which can be either\n   * new items or updates to existing items.\n   *\n   * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):\n   * - Set Activity.source to the issue's canonical URL (e.g., Linear issue URL, Jira issue URL)\n   * - Use Note.key for issue details:\n   *   - key: \"description\" for issue description (upserts on changes)\n   *   - key: \"metadata\" for status, priority, assignee, etc.\n   *   - key: \"comment-{commentId}\" for individual comments (unique per comment)\n   * - No manual ID tracking needed - Plot handles deduplication automatically\n   * - Send NewActivityWithNotes for all issues (creates new or updates existing)\n   * - Set activity.unread = false for initial sync, true for incremental updates\n   *\n   * **Alternative** (Strategy 3 - Advanced cases):\n   * - Use Uuid.Generate() and store ID mappings when creating multiple activities per issue\n   * - See SYNC_STRATEGIES.md for when this is appropriate\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to sync\n   * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced issue\n   * @param options - Optional configuration for limiting the sync scope (e.g., time range)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @returns Promise that resolves when sync setup is complete\n   */\n  startSync<\n    TCallback extends (\n      syncUpdate: SyncUpdate,\n      ...args: any[]\n    ) => any\n  >(\n    authToken: string,\n    projectId: string,\n    callback: TCallback,\n    options?: ProjectSyncOptions,\n    ...extraArgs: TCallback extends (\n      syncUpdate: any,\n      ...rest: infer R\n    ) => any\n      ? R\n      : []\n  ): Promise<void>;\n\n  /**\n   * Stops synchronizing issues from a specific project.\n   *\n   * @param authToken - Authorization token for access\n   * @param projectId - ID of the project to stop syncing\n   * @returns Promise that resolves when sync is stopped\n   */\n  stopSync(authToken: string, projectId: string): Promise<void>;\n\n  /**\n   * Updates an issue/task with new values.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync activity updates back to the external service.\n   *\n   * The update object contains only the fields that changed, plus id and source.\n   * Uses the combination of start and done to determine workflow state:\n   * - done set → Completed/Done state\n   * - done null + start set → In Progress/Active state\n   * - done null + start null → Backlog/Todo state\n   *\n   * @param authToken - Authorization token for access\n   * @param update - ActivityUpdate with changed fields (includes id and source)\n   * @returns Promise that resolves when the update is synced\n   */\n  updateIssue?(authToken: string, update: ActivityUpdate): Promise<void>;\n\n  /**\n   * Adds a comment to an issue/task.\n   *\n   * Optional method for bidirectional sync. When implemented, allows Plot to\n   * sync notes added to activities back as comments on the external service.\n   *\n   * @param authToken - Authorization token for access\n   * @param issueId - ID or key of the issue/task to comment on\n   * @param body - The comment text content\n   * @returns Promise that resolves when the comment is added\n   */\n  addIssueComment?(\n    authToken: string,\n    issueId: string,\n    body: string\n  ): Promise<void>;\n}\n";
 //# sourceMappingURL=projects.js.map

package/dist/llm-docs/common/projects.js.map

@@ -1 +1 @@
-{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,usLAAusL,CAAC"}
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../../src/llm-docs/common/projects.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,woMAAwoM,CAAC"}

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

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

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

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

package/dist/llm-docs/plot.js

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

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

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

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { type Priority } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, args?: any): Promise<any> {\n    return this.tools.callbacks.run(token, args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * **Important**: Values must be JSON-serializable. Functions, Symbols, and undefined values\n   * cannot be stored directly.\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+declare const _default: "import { type Priority } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, args?: any): Promise<any> {\n    return this.tools.callbacks.run(token, args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * **Important**: Values must be JSON-serializable. Functions and Symbols cannot be stored.\n   *\n   * **Handling undefined values:**\n   * - Object keys with undefined values are automatically removed\n   * - Arrays with undefined elements will throw a validation error\n   * - Use null instead of undefined for array elements\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Object keys with undefined are automatically removed\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   * // Stores: { name: \"test\" }\n   *\n   * // \u2705 Arrays: use null for optional values\n   * await this.set(\"items\", [1, null, 3]);\n   *\n   * // \u274C Arrays with undefined throw errors\n   * await this.set(\"items\", [1, undefined, 3]); // Error!\n   *\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
 export default _default;
 //# sourceMappingURL=tool.d.ts.map

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

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

package/dist/llm-docs/tool.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { type Priority } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, args?: any): Promise<any> {\n    return this.tools.callbacks.run(token, args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * **Important**: Values must be JSON-serializable. Functions, Symbols, and undefined values\n   * cannot be stored directly.\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+export default "import { type Priority } from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstrtact parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, args?: any): Promise<any> {\n    return this.tools.callbacks.run(token, args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * @template T - The expected type of the stored value\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * **Important**: Values must be JSON-serializable. Functions and Symbols cannot be stored.\n   *\n   * **Handling undefined values:**\n   * - Object keys with undefined values are automatically removed\n   * - Arrays with undefined elements will throw a validation error\n   * - Use null instead of undefined for array elements\n   *\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Object keys with undefined are automatically removed\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   * // Stores: { name: \"test\" }\n   *\n   * // ✅ Arrays: use null for optional values\n   * await this.set(\"items\", [1, null, 3]);\n   *\n   * // ❌ Arrays with undefined throw errors\n   * await this.set(\"items\", [1, undefined, 3]); // Error!\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored\n   * @param key - The storage key to use\n   * @param value - The value to store (must be JSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T>(key: string, value: T): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param priority - The priority context containing the priority ID\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(priority: Priority): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
 //# sourceMappingURL=tool.js.map

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

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