@plotday/twister 0.53.0 → 0.55.0

package/src/plot.ts

@@ -11,13 +11,13 @@ export { type AuthProvider } from "./tools/integrations";
 
 /**
  * @fileoverview
- * Core Plot entity types for working with threads, notes, priorities, and contacts.
+ * Core Plot entity types for working with threads, notes, focuses, and contacts.
  *
  * ## Type Pattern: Null vs Undefined Semantics
  *
  * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:
  *
- * ### Entity Types (Thread, Priority, Note, Actor)
+ * ### Entity Types (Thread, Focus, Note, Actor)
  * - **Required fields**: No `?`, cannot be `undefined`
  *   - Example: `id: Uuid`, `title: string`
  * - **Nullable fields**: Use `| null` to allow explicit clearing
@@ -30,10 +30,10 @@ export { type AuthProvider } from "./tools/integrations";
  *   - `null` = field included but not set
  *   - Value = field has a value
  *
- * ### New* Types (NewThread, NewNote, NewPriority)
+ * ### New* Types (NewThread, NewNote, NewFocus)
  * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:
  * - **Required fields**: Must be provided (no `?`)
- *   - Example: `title: string` in NewPriority
+ *   - Example: `title: string` in NewFocus
  * - **Optional fields**: Use `?` to make them optional
  *   - Example: `title?: string`, `author?: NewActor`
  *   - `undefined` (omitted) = don't set/update this field
@@ -76,7 +76,7 @@ export { type AuthProvider } from "./tools/integrations";
 export type ActorId = string & { readonly __brand: "ActorId" };
 
 /**
- * Theme colors for priorities.
+ * Theme colors for focuses.
  */
 export enum ThemeColor {
   /** Catalyst - Green */
@@ -98,73 +98,67 @@ export enum ThemeColor {
 }
 
 /**
- * Represents a priority context within Plot.
+ * Represents a focus within Plot.
  *
- * Priorities are similar to projects in other apps. All Activity is in a Priority.
- * Priorities can be nested.
+ * A focus is similar to a project or area-of-life. All Activity is in a Focus.
+ * Focuses are flat — they have no parent and no children. Threads not matched
+ * to any focus live in the Inbox.
  */
-export type Priority = {
-  /** Unique identifier for the priority */
+export type Focus = {
+  /** Unique identifier for the focus */
   id: Uuid;
-  /** Human-readable title for the priority */
+  /** Human-readable title for the focus */
   title: string;
-  /** Whether this priority has been archived */
+  /** Whether this focus has been archived */
   archived: boolean;
   /**
-   * Optional key for referencing this priority.
-   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).
+   * Optional key for referencing this focus.
+   * Keys are unique per user.
    */
   key: string | null;
-  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */
+  /** Optional theme color for the focus (0-7). Defaults to 7 (Resolution) when not set. */
   color: ThemeColor | null;
+  /** Optional icon for the focus (a curated icon key). Defaults to the focus icon when not set. */
+  icon: string | null;
 };
 
 /**
- * Type for creating new priorities.
+ * Type for creating new focuses.
  *
  * Supports multiple creation patterns:
- * - Provide a specific UUID for the priority
- * - Provide a key for upsert within the user's priorities
+ * - Provide a specific UUID for the focus
+ * - Provide a key for upsert within the user's focuses
  * - Omit both to auto-generate a new UUID
- *
- * Optionally specify a parent priority by ID or key for hierarchical structures.
  */
-export type NewPriority = Pick<Priority, "title"> &
-  Partial<Omit<Priority, "id" | "title">> &
+export type NewFocus = Pick<Focus, "title"> &
+  Partial<Omit<Focus, "id" | "title">> &
   (
     | {
         /**
-         * Unique identifier for the priority, generated by Uuid.Generate().
-         * Specifying an ID allows tools to track and upsert priorities.
+         * Unique identifier for the focus, generated by Uuid.Generate().
+         * Specifying an ID allows tools to track and upsert focuses.
          */
         id: Uuid;
       }
     | {
         /**
-         * Unique key for the priority within the user's priorities.
+         * Unique key for the focus within the user's focuses.
          * Can be used to upsert without knowing the UUID.
-         * For example, "@plot" identifies the Plot priority.
+         * For example, "@plot" identifies the Plot focus.
          */
         key: string;
       }
     | {
         /* Neither id nor key is required. An id will be generated and returned. */
       }
-  ) & {
-    /** Add the new priority as the child of another priority */
-    parent?: { id: Uuid } | { key: string };
-  };
+  );
 
 /**
- * Type for updating existing priorities.
- * Must provide either id or key to identify the priority to update.
- * Set `parent` to move the priority under a new parent (requires PriorityAccess.Full).
+ * Type for updating existing focuses.
+ * Must provide either id or key to identify the focus to update.
  */
-export type PriorityUpdate = ({ id: Uuid } | { key: string }) &
-  Partial<Pick<Priority, "title" | "archived">> & {
-    /** Move the priority under a new parent. Requires PriorityAccess.Full. */
-    parent?: { id: Uuid } | { key: string };
-  };
+export type FocusUpdate = ({ id: Uuid } | { key: string }) &
+  Partial<Pick<Focus, "title" | "archived">>;
 
 /**
  * Enumeration of supported action types.
@@ -375,9 +369,9 @@ export type ThreadMeta = {
 
 /**
  * Thread sub-type that determines the thread's icon and category.
- * Available types depend on whether the priority is shared:
- * - Private priorities: "action" (default for tasks), "notes" (default), "idea", "goal", "decision"
- * - Shared priorities: all above plus "discussion" (default), "announcement", "ask"
+ * Available types depend on whether the focus is shared:
+ * - Private focuses: "action" (default for tasks), "notes" (default), "idea", "goal", "decision"
+ * - Shared focuses: all above plus "discussion" (default), "announcement", "ask"
  */
 export type ThreadType =
   | "action"
@@ -430,8 +424,8 @@ export type NewReactions = Record<Reaction, NewActor[]>;
 
 /**
  * Thread access level determining visibility.
- * - "public": Visible to all users with priority access
- * - "members": Visible to priority members (default for shared priorities)
+ * - "public": Visible to all users with focus access
+ * - "members": Visible to focus members (default for shared focuses)
  * - "private": Visible only to creator and contacts listed in accessContacts
  */
 export type ThreadAccessLevel = "public" | "members" | "private";
@@ -469,8 +463,8 @@ export type ThreadCommon = {
 type ThreadFields = ThreadCommon & {
   /** The display title/summary of the thread */
   title: string;
-  /** The priority context this thread belongs to */
-  priority: Priority;
+  /** The focus context this thread belongs to */
+  focus: Focus;
   /** The thread's sub-type/category. Determines the displayed icon. */
   type: ThreadType | null;
   /** Thread access level: "public", "members", or "private" */
@@ -506,7 +500,7 @@ export type NewThreadWithNotes = NewThread & {
  * ```
  */
 export type NewThread = Partial<
-  Omit<ThreadFields, "priority" | "tags" | "reactions" | "id" | "accessContacts">
+  Omit<ThreadFields, "focus" | "tags" | "reactions" | "id" | "accessContacts">
 > &
   (
     | {
@@ -518,8 +512,8 @@ export type NewThread = Partial<
       }
   ) &
   {
-    /** Explicit priority - disables automatic priority matching. When omitted, the server classifies the thread using the user's priority rules. */
-    priority?: Pick<Priority, "id">;
+    /** Explicit focus - disables automatic focus matching. When omitted, the server classifies the thread using the user's focus rules. */
+    focus?: Pick<Focus, "id">;
   } & {
     /**
      * All tags to set on the new thread.
@@ -550,7 +544,7 @@ export type NewThread = Partial<
      * - undefined/omitted (default): Thread is unread for users, except auto-marked
      *   as read for the author if they are the twist owner (user)
      * - true: Thread is explicitly unread for ALL users (use sparingly)
-     * - false: Thread is marked as read for all users in the priority at creation time
+     * - false: Thread is marked as read for all users in the focus at creation time
      */
     unread?: boolean;
 
@@ -638,10 +632,10 @@ type ThreadSingleUpdateFields = ThreadBulkUpdateFields & {
   preview?: string | null;
 
   /**
-   * Move the thread to a different priority. Requires ThreadAccess.Full.
-   * The target priority must be owned by the twist's user.
+   * Move the thread to a different focus. Requires ThreadAccess.Full.
+   * The target focus must be owned by the twist's user.
    */
-  priority?: Pick<Priority, "id">;
+  focus?: Pick<Focus, "id">;
 };
 
 export type ThreadUpdate =
@@ -699,7 +693,7 @@ export type Note = ThreadCommon & {
    * When set (even to []), the note is private to the listed contacts plus the creator.
    */
   accessContacts: ActorId[] | null;
-  /** Priority twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */
+  /** Focus twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */
   mentions: ActorId[];
 };
 
@@ -771,7 +765,7 @@ export type NewNote = Partial<
      * - undefined/omitted (default): Thread is unread for users, except auto-marked
      *   as read for the author if they are the twist owner (user)
      * - true: Thread is explicitly unread for ALL users (use sparingly)
-     * - false: Thread is marked as read for all users in the priority at note creation time
+     * - false: Thread is marked as read for all users in the focus at note creation time
      *
      * For the default behavior, omit this field entirely.
      * Use false for initial sync to avoid marking historical items as unread.
@@ -1044,7 +1038,7 @@ export type NewLink = Partial<
 > & {
   /**
    * Canonical ID for the item in an external system.
-   * When set, uniquely identifies the link within a priority tree. This performs
+   * When set, uniquely identifies the link for the user. This performs
    * an upsert.
    *
    * @deprecated Pass `sources: [...]` instead. Both fields can be set during
@@ -1078,7 +1072,7 @@ export type NewLink = Partial<
      * Whether the thread should be marked as unread for users.
      * - undefined/omitted (default): Thread is unread for users, except auto-marked
      *   as read for the author if they are the twist owner (user)
-     * - false: Thread is marked as read for all users in the priority at creation time
+     * - false: Thread is marked as read for all users in the focus at creation time
      */
     unread?: boolean;
     /**
@@ -1089,11 +1083,11 @@ export type NewLink = Partial<
      */
     archived?: boolean;
     /**
-     * Explicit priority (disables automatic priority matching).
+     * Explicit focus (disables automatic focus matching).
      * Only used when the link creates a new thread. When omitted, the
-     * server classifies the thread using the user's priority rules.
+     * server classifies the thread using the user's focus rules.
      */
-    priority?: Pick<Priority, "id">;
+    focus?: Pick<Focus, "id">;
   };
 
 /**
@@ -1141,8 +1135,8 @@ export type PlanOperation =
       /** Current thread title for display */
       threadTitle: string;
       changes: Partial<Pick<ThreadFields, "archived" | "title" | "type">> & {
-        /** Move to this priority */
-        priority?: { id: Uuid; title: string };
+        /** Move to this focus */
+        focus?: { id: Uuid; title: string };
       };
     }
   | {
@@ -1159,9 +1153,9 @@ export type PlanOperation =
   | {
       type: "createThread";
       title: string;
-      priorityId: Uuid;
-      /** Priority title for display */
-      priorityTitle: string;
+      focusId: Uuid;
+      /** Focus title for display */
+      focusTitle: string;
     }
   | {
       type: "createNote";
@@ -1171,12 +1165,9 @@ export type PlanOperation =
       content: string;
     }
   | {
-      type: "updatePriority";
-      priorityId: Uuid;
-      /** Current priority title for display */
-      priorityTitle: string;
-      changes: Partial<Pick<Priority, "title" | "archived">> & {
-        /** Move under this parent */
-        parent?: { id: Uuid; title: string };
-      };
+      type: "updateFocus";
+      focusId: Uuid;
+      /** Current focus title for display */
+      focusTitle: string;
+      changes: Partial<Pick<Focus, "title" | "archived">>;
     };

package/src/schedule.ts

@@ -14,7 +14,7 @@ export { Uuid } from "./utils/uuid";
  * Represents a schedule entry for a thread.
  *
  * Schedules define when a thread occurs in time. A thread may have zero or more schedules:
- * - Shared schedules (userId is null): visible to all members of the thread's priority
+ * - Shared schedules (userId is null): visible to all members of the thread's focus
  * - Per-user schedules (userId set): private ordering/scheduling for a specific user
  *
  * For recurring events in the SDK, start/end represent the first occurrence's

package/src/tools/ai.ts

@@ -69,8 +69,11 @@ export abstract class AI extends ITool {
    * Returns which AI capabilities are currently available.
    * Check this before calling prompt() or embed() to gracefully
    * handle cases where AI is disabled by the user.
+   *
+   * Built-in tools are accessed as RPC stubs, so from a twist this call
+   * resolves asynchronously — always `await` it.
    */
-  abstract available(): AICapabilities;
+  abstract available(): AICapabilities | Promise<AICapabilities>;
 
   /**
    * Sends a request to an AI model and returns the response using the Vercel AI SDK.
@@ -134,7 +137,7 @@ export abstract class AI extends ITool {
    *   tools: {
    *     getWeather: {
    *       description: "Get weather for a city",
-   *       parameters: Type.Object({
+   *       inputSchema: Type.Object({
    *         city: Type.String()
    *       }),
    *       execute: async ({ city }) => {
@@ -165,6 +168,12 @@ export type AICapabilities = {
   prompt: boolean;
   /** Whether AI embedding generation is available. */
   embed: boolean;
+  /**
+   * Whether provider-native web search is available. True for Plot AI and
+   * Anthropic/Google BYOK providers; false for OpenAI/custom BYOK providers
+   * that don't expose a server-side web search tool through this runtime.
+   */
+  webSearch: boolean;
 };
 
 /**
@@ -345,6 +354,31 @@ export interface AIRequest<
    * Controls diversity by limiting to top probability tokens.
    */
   topP?: number;
+
+  /**
+   * Enable provider-native web search so the model can retrieve
+   * up-to-date information from the web. The search is executed
+   * server-side by the provider and any pages used are returned in
+   * {@link AIResponse.sources}.
+   *
+   * Only available on web-search-capable providers (Anthropic and
+   * Google). Check {@link AICapabilities.webSearch} via `available()`
+   * before relying on it; on unsupported providers the flag is ignored.
+   *
+   * Pass `true` for defaults, or an object to cap the number of searches.
+   */
+  webSearch?: boolean | { maxUses?: number };
+
+  /**
+   * Maximum number of sequential generation steps for agentic tool use.
+   * When the model calls a tool, its result is fed back and the model is
+   * called again, up to `maxSteps` times, until it produces a final answer.
+   *
+   * Defaults to 1 (single step — tool calls are returned but not looped),
+   * preserving prior behavior. Set higher (e.g. 6) to let the model chain
+   * tool calls into a final answer.
+   */
+  maxSteps?: number;
 }
 
 /**
@@ -742,17 +776,19 @@ export interface ToolExecutionOptions {
  */
 export type AITool<PARAMETERS extends ToolParameters = any, RESULT = any> = {
   /**
-   * The schema of the input that the tool expects. The language model will use this to generate the input.
-   * It is also used to validate the output of the language model.
-   * Use descriptions to make the input understandable for the language model.
+   * The schema of the input that the tool expects, expressed as a Typebox
+   * schema. The language model uses this to generate (and the runtime to
+   * validate) the tool input. Use field descriptions to make the input
+   * understandable for the model.
+   *
+   * This is the canonical field read by the runtime. `parameters` is an
+   * accepted alias for backwards compatibility.
    */
-  parameters: PARAMETERS;
+  inputSchema: TSchema;
   /**
-   * The schema of the input that the tool expects. The language model will use this to generate the input.
-   * It is also used to validate the output of the language model.
-   * Use descriptions to make the input understandable for the language model.
+   * @deprecated Alias for {@link inputSchema}. Prefer `inputSchema`.
    */
-  inputSchema: TSchema;
+  parameters?: PARAMETERS;
   /**
    * An optional description of what the tool does.
    * Will be used by the language model to decide whether to use the tool.

package/src/tools/files.ts

@@ -14,7 +14,7 @@ import { ITool } from "..";
  */
 export abstract class Files extends ITool {
   /**
-   * Read a file uploaded by a client and attached to a note in a priority
+   * Read a file uploaded by a client and attached to a note in a focus
    * where this twist is installed.
    *
    * @param fileId The id from an ActionType.file action.

package/src/tools/integrations.ts

@@ -17,6 +17,26 @@ export type Channel = {
   id: string;
   /** Display name shown in the UI */
   title: string;
+  /**
+   * Whether this channel should be selected by default when the user first
+   * adds the connection. Tri-state:
+   * - `true`  — pre-select it (e.g. the user's own/primary calendar).
+   * - `false` — exclude it from the default selection (low-value or
+   *   irrelevant resources that would crowd the user's view, or containers
+   *   whose contents are too broad to sync wholesale — e.g. a holiday or
+   *   someone-else's shared calendar, a GitHub org that cascades to every
+   *   repo, a Microsoft Teams team container). The user can still enable it
+   *   manually.
+   * - `undefined` — no opinion; the client decides. The client defaults to
+   *   enabling the channel unless its title looks low-value (holidays,
+   *   birthdays, spam/sent/draft, …).
+   *
+   * The guiding principle is "sync everything the user would reasonably want
+   * by default" — for most connectors that's all channels, so only set this
+   * where the connector can distinguish the user's own/relevant channels from
+   * low-value ones (e.g. Google Calendar via `accessRole === "owner"`).
+   */
+  enabledByDefault?: boolean;
   /** Optional nested channel resources (e.g., subfolders) */
   children?: Channel[];
   /** Per-channel link type configs. Overrides twist-level linkTypes when present. */
@@ -39,6 +59,28 @@ export type LinkTypeConfig = {
    * when omitted. Use the singular noun in title case (e.g. "Comment").
    */
   noteLabel?: string;
+  /**
+   * Placeholder shown in the editor when this link type is the target of a
+   * new thread (NewThreadPage). Example: "Send a Gmail email".
+   * If unset, Plot derives "Create a new {connector} {label.toLowerCase()}".
+   */
+  composePlaceholder?: string;
+  /**
+   * Label for the Send button on NewThreadPage when this link type is the
+   * target. Example: "Send". If unset, defaults to "Create".
+   */
+  composeVerb?: string;
+  /**
+   * Placeholder shown in the in-thread editor for the default reply mode.
+   * Example: "Reply" (Gmail), "Add a comment" (Linear). If unset, Plot derives
+   * "Add a {noteLabel.toLowerCase()}" or "Add a note".
+   */
+  replyPlaceholder?: string;
+  /**
+   * Label for the Send button in the in-thread editor. Example: "Send"
+   * (Gmail), "Comment" (Linear). If unset, defaults to "Send".
+   */
+  replyVerb?: string;
   /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */
   logo?: string;
   /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */
@@ -62,32 +104,26 @@ export type LinkTypeConfig = {
      */
     active?: boolean;
     /**
-     * Mark the thread `task=true` in Plot when a link enters this status.
-     * Use for project-tracker assignments — Linear / Todoist / Jira / etc.
-     * `task` puts the thread on the user's task list without flooding their
-     * inbox under `active`: the user explicitly flips it to `active` when
-     * they decide to start.
-     */
-    task?: boolean;
-    /**
-     * Mark the thread `to_read=true` in Plot when a link enters this status.
-     * Use for connectors that explicitly track read-later state (Pocket
-     * archives, Slack "remind me", etc).
-     */
-    toRead?: boolean;
-    /**
-     * @deprecated Use `active` (messaging) or `task` (project tracker) instead.
-     * Treated as `task: true` for backward compatibility.
-     *
-     * Original meaning: whether this status represents the connector's
-     * "to-do" / active state. When a user adds a thread to Plot's agenda,
-     * done-status links flip to the status marked `todo: true` (e.g.,
-     * Gmail's "starred", Linear's "todo").
+     * Marks this status as the connector's "to-do" / active state. When a
+     * user brings a done thread back into Plot's agenda, done-status links
+     * are flipped to the status marked `todo: true` (e.g. Gmail's "starred",
+     * Linear's "unstarted"); connectors that don't mark one fall back to the
+     * first non-done status.
      */
     todo?: boolean;
   }>;
   /** Whether this link type supports displaying and changing the assignee */
   supportsAssignee?: boolean;
+  /**
+   * Whether this link type produces time-anchored schedule/agenda items
+   * (i.e. calendar events). The Plot app shows the agenda (the bottom-nav
+   * tab on mobile and the left-sidebar agenda on desktop) only when the
+   * user has at least one active connection whose link types include one
+   * with `includesSchedules: true`. Calendar connectors (Google / Apple /
+   * Outlook Calendar) set this on their `event` link type. Defaults to
+   * false — non-calendar link types (messages, issues, tasks, docs) omit it.
+   */
+  includesSchedules?: boolean;
   /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */
   defaultCreateThreads?: string;
   /**
@@ -119,6 +155,22 @@ export type LinkTypeConfig = {
    * false when omitted.
    */
   supportsContactChanges?: boolean;
+  /**
+   * Whether a note/reply on this link type can carry a link (a pasted URL or
+   * connector-created item) that Plot forwards to the source. When false (the
+   * default), the "Add link" button is hidden for threads of this link type.
+   * Only set true if the connector's reply path actually forwards the link
+   * action to the source. Private Plot notes (no link type) always allow links.
+   */
+  supportsLinks?: boolean;
+  /**
+   * Whether a note/reply on this link type can carry an uploaded file that Plot
+   * forwards to the source as an attachment. When false (the default), the
+   * "Attach file" button is hidden for threads of this link type. Only set true
+   * if the connector's reply path actually uploads file actions to the source.
+   * Private Plot notes (no link type) always allow attachments.
+   */
+  supportsFileAttachments?: boolean;
   /**
    * Declares how sharing on threads of this link type is scoped:
    *
@@ -130,12 +182,16 @@ export type LinkTypeConfig = {
    * - `"message"`: each note carries its own recipient set via
    *   `note.access_contacts`; the thread roster is the union across
    *   all messages. Email.
+   * - `"none"`: the link type has no recipient roster at all. No
+   *   contacts/sharing UI is shown for these threads. Use for purely
+   *   personal destinations with no sharing concept (e.g. Google
+   *   Tasks). The per-thread `contacts` array is ignored for sharing UI.
    *
    * Omit to default to `"thread"`. When set to `"message"`, every
    * note this connector ingests must populate `access_contacts`
    * explicitly (never NULL).
    */
-  sharingModel?: "thread" | "channel" | "message";
+  sharingModel?: "thread" | "channel" | "message" | "none";
 };
 
 /**
@@ -316,7 +372,7 @@ export abstract class Integrations extends ITool {
   abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;
 
   /**
-   * Saves a link with notes to the connector's priority.
+   * Saves a link with notes to the connector's focus.
    *
    * Creates a thread+link pair. The thread is a lightweight container;
    * the link holds the external entity data (source, meta, type, status, etc.).
@@ -355,7 +411,7 @@ export abstract class Integrations extends ITool {
   abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;
 
   /**
-   * Upserts contacts into the connector's priority without requiring a Link.
+   * Upserts contacts into the connector's focus without requiring a Link.
    *
    * Use this for messaging connectors to bulk-sync workspace members so the
    * recipient picker can filter contacts by reachable platform account. Populate