Plot search and thread references

Author: KrisBraun

.changeset/search-notes-links.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: Semantic search tool for notes and links in the Plot tool, with configurable limit, threshold, and priority scope

.changeset/thread-reference-actions.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: Thread reference action type for navigating to related threads

twister/src/plot.ts

@@ -180,6 +180,8 @@ export enum ActionType {
   conferencing = "conferencing",
   /** File attachment links stored in R2 */
   file = "file",
+  /** Thread reference links for navigating to related threads */
+  thread = "thread",
 }
 
 /**
@@ -288,6 +290,12 @@ export type Action =
       fileSize: number;
       /** MIME type of the file */
       mimeType: string;
+    }
+  | {
+      /** Thread reference action for navigating to a related thread */
+      type: ActionType.thread;
+      /** UUID of the referenced thread */
+      threadId: Uuid;
     };
 
 /**

twister/src/tools/plot.ts

@@ -83,6 +83,42 @@ export type LinkFilter = {
   limit?: number;
 };
 
+type SearchResultBase = {
+  thread: { id: string; title: string | null };
+  priority: { id: string; title: string | null };
+  similarity: number;
+};
+
+export type NoteSearchResult = SearchResultBase & {
+  type: 'note';
+  id: string;
+  content: string | null;
+};
+
+export type LinkSearchResult = SearchResultBase & {
+  type: 'link';
+  id: string;
+  title: string | null;
+  sourceUrl: string | null;
+  content: string | null;
+};
+
+export type SearchResult = NoteSearchResult | LinkSearchResult;
+
+/** Default number of search results returned */
+export const SEARCH_DEFAULT_LIMIT = 10;
+/** Maximum number of search results allowed */
+export const SEARCH_MAX_LIMIT = 30;
+
+export type SearchOptions = {
+  /** Max results to return (default: 10, max: 30) */
+  limit?: number;
+  /** Minimum similarity score 0-1 (default: 0.3) */
+  threshold?: number;
+  /** Scope search to this priority + descendants (default: twist's installed priority). Must be within the twist's allowed scope. */
+  priorityId?: string;
+};
+
 /**
  * Built-in tool for interacting with the core Plot data layer.
  *
@@ -197,6 +233,8 @@ export abstract class Plot extends ITool {
     contact?: {
       access?: ContactAccess;
     };
+    /** Enable semantic search across notes and links in the twist's priority scope. */
+    search?: true;
   };
 
   /**
@@ -518,4 +556,16 @@ export abstract class Plot extends ITool {
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;
+
+  /**
+   * Searches notes and links using semantic similarity.
+   *
+   * Requires `search: true` in Plot options.
+   *
+   * @param query - The search query text
+   * @param options - Optional search configuration
+   * @returns Promise resolving to array of search results ordered by similarity
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
 }