@plotday/twister 0.43.0 → 0.45.0

package/dist/tools/plot.d.ts

@@ -1,5 +1,6 @@
-import { type Thread, type ThreadUpdate, type Actor, type ActorId, ITool, type Link, type NewThread, type NewThreadWithNotes, type NewNote, type NewPriority, type Note, type NoteUpdate, type Priority, type PriorityUpdate, Uuid } from "..";
+import { type Action, type Thread, type ThreadUpdate, type Actor, type ActorId, ITool, type Link, type LinkUpdate, type NewThread, type NewThreadWithNotes, type NewNote, type NewPriority, type Note, type NoteUpdate, type PlanOperation, type Priority, type PriorityUpdate, Uuid } from "..";
 import { type Schedule, type NewSchedule } from "../schedule";
+import type { Callback } from "./callbacks";
 export declare enum ThreadAccess {
     /**
      * Create new Note on a Thread where the twist was mentioned.
@@ -11,18 +12,25 @@ export declare enum ThreadAccess {
      * Create new Note in a Thread the twist created.
      * All Respond permissions.
      */
-    Create = 1
+    Create = 1,
+    /**
+     * List/query all Threads owned by the twist's user.
+     * Update any Thread (title, tags, archived, type, priority) regardless of creator.
+     * Create Notes on any Thread (not just own or mentioned).
+     * All Create permissions.
+     */
+    Full = 2
 }
 export declare enum PriorityAccess {
     /**
-     * Create a new Priority within the twist's Priority.
-     * Update Priority created by the twist.
+     * Create new Priorities under the twist owner's priority tree.
+     * Update Priorities created by the twist.
      */
     Create = 0,
     /**
-     * Read all Priority within the twist's Priority.
-     * Create a new Priority within the twist's Priority.
-     * Update and archive any Priority within the twist's Priority.
+     * Read all Priorities owned by the twist's user.
+     * Create new Priorities under the twist owner's priority tree.
+     * Update and archive any Priority owned by the twist's user.
      */
     Full = 1
 }
@@ -30,6 +38,12 @@ export declare enum ContactAccess {
     /** Read existing contact details. Without this, only the ID will be provided. */
     Read = 0
 }
+export declare enum LinkAccess {
+    /** Read links on any thread owned by the twist's user. */
+    Read = 0,
+    /** Read + update links, including moving links between threads owned by the twist's user. */
+    Full = 1
+}
 /**
  * Intent handler for thread mentions.
  * Defines how the twist should respond when mentioned in a thread.
@@ -88,7 +102,11 @@ export type SearchOptions = {
     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. */
+    /**
+     * Scope search to this priority + descendants. Must be owned by the twist
+     * owner. When omitted, the server scopes the search to the owner's entire
+     * priority tree.
+     */
     priorityId?: string;
 };
 /**
@@ -108,7 +126,7 @@ export type SearchOptions = {
  *     this.plot = tools.get(Plot);
  *   }
  *
- *   async activate(priority) {
+ *   async activate() {
  *     // Create a welcome thread
  *     await this.plot.createThread({
  *       title: "Welcome to Plot!",
@@ -202,15 +220,24 @@ export declare abstract class Plot extends ITool {
             intents?: NoteIntentHandler[];
         };
         /** Enable link processing from connected source channels. */
-        link?: true;
+        link?: true | {
+            /** Access level for links. When omitted with `link: true`, only source channel links are accessible. */
+            access?: LinkAccess;
+        };
         priority?: {
             access?: PriorityAccess;
         };
         contact?: {
             access?: ContactAccess;
         };
-        /** Enable semantic search across notes and links in the twist's priority scope. */
+        /** Enable semantic search across notes and links owned by the twist's user. */
         search?: true;
+        /**
+         * When true, admin write operations (on threads/notes/links/priorities not created by this twist)
+         * require user approval via plan actions instead of executing immediately.
+         * Read operations and operations on the twist's own content still work directly.
+         */
+        requireApproval?: boolean;
     };
     /**
      * Creates a new thread in the Plot system.
@@ -458,6 +485,22 @@ export declare abstract class Plot extends ITool {
      * the owner's name or email is needed.
      */
     abstract getOwner(): Promise<Actor>;
+    /**
+     * Returns the user ID (`twist_instance.owner_id`) that installed this
+     * twist. This is the same value exposed on Twist via `this.userId`.
+     */
+    abstract getUserId(): Promise<string>;
+    /**
+     * Returns the owner user's root priority ID. Used as the implicit default
+     * when an operation needs a priority but the caller didn't supply one —
+     * for example, `plot.createPriority()` without a parent, or
+     * `plot.getThreads()` without an explicit `priorityId`.
+     *
+     * On the server, priority resolution for newly created threads/links
+     * happens automatically via `match_priority_for_user`; twists rarely need
+     * to call this directly.
+     */
+    abstract getDefaultPriorityId(): Promise<string>;
     /**
      * Creates a new schedule for a thread.
      *
@@ -511,6 +554,76 @@ export declare abstract class Plot extends ITool {
      * @returns Promise resolving to array of search results ordered by similarity
      */
     abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Lists threads owned by the twist's user.
+     *
+     * Requires `ThreadAccess.Full`.
+     *
+     * @param options - Query options for filtering threads
+     * @returns Promise resolving to array of threads
+     */
+    abstract getThreads(options?: {
+        /**
+         * Priority to list threads from. Must be owned by the twist owner.
+         * When omitted, defaults to the owner's root priority.
+         */
+        priorityId?: Uuid;
+        /** Include threads from descendant priorities. Default: true. */
+        includeDescendants?: boolean;
+        /** Include archived threads. Default: false. */
+        includeArchived?: boolean;
+        /** Maximum number of threads to return. Default: 50, max: 200. */
+        limit?: number;
+        /** Number of threads to skip for pagination. Default: 0. */
+        offset?: number;
+    }): Promise<Thread[]>;
+    /**
+     * Lists priorities owned by the twist's user.
+     *
+     * Requires `PriorityAccess.Full`.
+     *
+     * @param options - Query options for filtering priorities
+     * @returns Promise resolving to array of priorities
+     */
+    abstract getPriorities(options?: {
+        /**
+         * Parent priority to list children of. Must be owned by the twist
+         * owner. When omitted, defaults to the owner's root priority.
+         */
+        parentId?: Uuid;
+        /** Include all descendants, not just direct children. Default: false. */
+        includeDescendants?: boolean;
+        /** Include archived priorities. Default: false. */
+        includeArchived?: boolean;
+    }): Promise<Priority[]>;
+    /**
+     * Updates a link.
+     *
+     * Requires `LinkAccess.Full`. Set `threadId` to move the link to a different thread.
+     *
+     * @param link - The link update containing the ID and fields to change
+     * @returns Promise that resolves when the update is complete
+     */
+    abstract updateLink(link: LinkUpdate): Promise<void>;
+    /**
+     * Creates a plan of operations for user approval.
+     *
+     * Returns an Action that can be attached to a note. The user can approve,
+     * deny, or request changes. On approval, operations are executed by the API.
+     *
+     * Requires `requireApproval: true` in Plot options.
+     *
+     * @param options - Plan configuration
+     * @returns An Action of type `plan` to attach to a note
+     */
+    abstract createPlan(options: {
+        /** Human-readable title summarizing the plan */
+        title: string;
+        /** Array of operations to execute on approval */
+        operations: PlanOperation[];
+        /** Callback invoked with (action, approved: boolean) when the user responds */
+        callback: Callback;
+    }): Action;
 }
 export {};
 //# sourceMappingURL=plot.d.ts.map

package/dist/tools/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,KAAK,EACL,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,IAAI,EACL,MAAM,IAAI,CAAC;AACZ,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAErB,oBAAY,YAAY;IACtB;;;OAGG;IACH,OAAO,IAAA;IACP;;;;OAIG;IACH,MAAM,IAAA;CACP;AAED,oBAAY,cAAc;IACxB;;;OAGG;IACH,MAAM,IAAA;IACN;;;;OAIG;IACH,IAAI,IAAA;CACL;AAED,oBAAY,aAAa;IACvB,iFAAiF;IACjF,IAAI,IAAA;CACL;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uDAAuD;IACvD,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,yDAAyD;IACzD,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACtB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7C,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE/D,gDAAgD;AAChD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,MAAM,MAAM,aAAa,GAAG;IAC1B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mIAAmI;IACnI,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,8BAAsB,IAAK,SAAQ,KAAK;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;QACvB,MAAM,CAAC,EAAE;YACP;;;eAGG;YACH,MAAM,CAAC,EAAE,YAAY,CAAC;YACtB,4FAA4F;YAC5F,cAAc,CAAC,EAAE,OAAO,CAAC;SAC1B,CAAC;QACF,IAAI,CAAC,EAAE;YACL,2FAA2F;YAC3F,cAAc,CAAC,EAAE,OAAO,CAAC;YACzB;;;;;;;;;;;;;;;;;;eAkBG;YACH,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;SAC/B,CAAC;QACF,6DAA6D;QAC7D,IAAI,CAAC,EAAE,IAAI,CAAC;QACZ,QAAQ,CAAC,EAAE;YACT,MAAM,CAAC,EAAE,cAAc,CAAC;SACzB,CAAC;QACF,OAAO,CAAC,EAAE;YACR,MAAM,CAAC,EAAE,aAAa,CAAC;SACxB,CAAC;QACF,mFAAmF;QACnF,MAAM,CAAC,EAAE,IAAI,CAAC;KACf,CAAC;IAEF;;;;;;;;;OASG;IAEH,QAAQ,CAAC,YAAY,CACnB,MAAM,EAAE,SAAS,GAAG,kBAAkB,GACrC,OAAO,CAAC,IAAI,CAAC;IAEhB;;;;;;;;;OASG;IAEH,QAAQ,CAAC,aAAa,CACpB,OAAO,EAAE,CAAC,SAAS,GAAG,kBAAkB,CAAC,EAAE,GAC1C,OAAO,CAAC,IAAI,EAAE,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IAEH,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1D;;;;;;;;;OASG;IAEH,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IAEH,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IAEH,QAAQ,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IAEH,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAEpD;;;;;;;;;OASG;IAEH,QAAQ,CAAC,SAAS,CAChB,MAAM,EAAE;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GACxC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;;;OASG;IAEH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAE5E;;;;;;;;OAQG;IAEH,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,GAAG;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAExF;;;;;;;OAOG;IAEH,QAAQ,CAAC,WAAW,CAClB,QAAQ,EAAE;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GACvC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAE3B;;;;;;;;OAQG;IAEH,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9D;;;;;;;;OAQG;IAEH,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAEpD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IAEH,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAEjE;;;;;OAKG;IAEH,QAAQ,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAE1D;;;;;;;OAOG;IAEH,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE,CAAC,CAAC;IAErF;;;;;;;;OAQG;IAEH,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CACjF"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"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"}

package/dist/tools/plot.js

@@ -12,18 +12,25 @@ export var ThreadAccess;
      * All Respond permissions.
      */
     ThreadAccess[ThreadAccess["Create"] = 1] = "Create";
+    /**
+     * List/query all Threads owned by the twist's user.
+     * Update any Thread (title, tags, archived, type, priority) regardless of creator.
+     * Create Notes on any Thread (not just own or mentioned).
+     * All Create permissions.
+     */
+    ThreadAccess[ThreadAccess["Full"] = 2] = "Full";
 })(ThreadAccess || (ThreadAccess = {}));
 export var PriorityAccess;
 (function (PriorityAccess) {
     /**
-     * Create a new Priority within the twist's Priority.
-     * Update Priority created by the twist.
+     * Create new Priorities under the twist owner's priority tree.
+     * Update Priorities created by the twist.
      */
     PriorityAccess[PriorityAccess["Create"] = 0] = "Create";
     /**
-     * Read all Priority within the twist's Priority.
-     * Create a new Priority within the twist's Priority.
-     * Update and archive any Priority within the twist's Priority.
+     * Read all Priorities owned by the twist's user.
+     * Create new Priorities under the twist owner's priority tree.
+     * Update and archive any Priority owned by the twist's user.
      */
     PriorityAccess[PriorityAccess["Full"] = 1] = "Full";
 })(PriorityAccess || (PriorityAccess = {}));
@@ -32,6 +39,13 @@ export var ContactAccess;
     /** Read existing contact details. Without this, only the ID will be provided. */
     ContactAccess[ContactAccess["Read"] = 0] = "Read";
 })(ContactAccess || (ContactAccess = {}));
+export var LinkAccess;
+(function (LinkAccess) {
+    /** Read links on any thread owned by the twist's user. */
+    LinkAccess[LinkAccess["Read"] = 0] = "Read";
+    /** Read + update links, including moving links between threads owned by the twist's user. */
+    LinkAccess[LinkAccess["Full"] = 1] = "Full";
+})(LinkAccess || (LinkAccess = {}));
 /** Default number of search results returned */
 export const SEARCH_DEFAULT_LIMIT = 10;
 /** Maximum number of search results allowed */
@@ -53,7 +67,7 @@ export const SEARCH_MAX_LIMIT = 30;
  *     this.plot = tools.get(Plot);
  *   }
  *
- *   async activate(priority) {
+ *   async activate() {
  *     // Create a welcome thread
  *     await this.plot.createThread({
  *       title: "Welcome to Plot!",

package/dist/tools/plot.js.map

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,GAWN,MAAM,IAAI,CAAC;AAMZ,MAAM,CAAN,IAAY,YAYX;AAZD,WAAY,YAAY;IACtB;;;OAGG;IACH,qDAAO,CAAA;IACP;;;;OAIG;IACH,mDAAM,CAAA;AACR,CAAC,EAZW,YAAY,KAAZ,YAAY,QAYvB;AAED,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,uDAAM,CAAA;IACN;;;;OAIG;IACH,mDAAI,CAAA;AACN,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAED,MAAM,CAAN,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,iFAAiF;IACjF,iDAAI,CAAA;AACN,CAAC,EAHW,aAAa,KAAb,aAAa,QAGxB;AAmDD,gDAAgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAWnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAgB,IAAK,SAAQ,KAAK;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAU,OAAO,CA4CrB;CAsUH"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/tools/plot.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,GAaN,MAAM,IAAI,CAAC;AAOZ,MAAM,CAAN,IAAY,YAmBX;AAnBD,WAAY,YAAY;IACtB;;;OAGG;IACH,qDAAO,CAAA;IACP;;;;OAIG;IACH,mDAAM,CAAA;IACN;;;;;OAKG;IACH,+CAAI,CAAA;AACN,CAAC,EAnBW,YAAY,KAAZ,YAAY,QAmBvB;AAED,MAAM,CAAN,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,uDAAM,CAAA;IACN;;;;OAIG;IACH,mDAAI,CAAA;AACN,CAAC,EAZW,cAAc,KAAd,cAAc,QAYzB;AAED,MAAM,CAAN,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,iFAAiF;IACjF,iDAAI,CAAA;AACN,CAAC,EAHW,aAAa,KAAb,aAAa,QAGxB;AAED,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACpB,0DAA0D;IAC1D,2CAAI,CAAA;IACJ,6FAA6F;IAC7F,2CAAI,CAAA;AACN,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB;AAmDD,gDAAgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAenC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAgB,IAAK,SAAQ,KAAK;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAU,OAAO,CAqDrB;CAsaH"}

package/dist/tools/smtp.d.ts

@@ -0,0 +1,155 @@
+import { ITool } from "..";
+/** Opaque session handle returned by connect(). */
+export type SmtpSession = string;
+/** Credentials and server info for connecting to an SMTP server. */
+export type SmtpConnectOptions = {
+    /** SMTP server hostname (e.g. "smtp.mail.me.com") */
+    host: string;
+    /** SMTP server port (e.g. 465 for TLS, 587 for STARTTLS) */
+    port: number;
+    /** Whether to use implicit TLS (true for port 465) */
+    tls: boolean;
+    /** Whether to upgrade to TLS via STARTTLS (true for port 587) */
+    starttls: boolean;
+    /** SMTP username (typically the email address) */
+    username: string;
+    /** SMTP password (app-specific password for Apple) */
+    password: string;
+};
+/** An email address with optional display name. */
+export type SmtpAddress = {
+    /** Display name (e.g. "John Doe") */
+    name?: string;
+    /** Email address (e.g. "john@example.com") */
+    address: string;
+};
+/** An email message to send. */
+export type SmtpMessage = {
+    /** Sender address */
+    from: SmtpAddress;
+    /** Primary recipients */
+    to: SmtpAddress[];
+    /** Carbon copy recipients */
+    cc?: SmtpAddress[];
+    /** Blind carbon copy recipients (not visible in headers) */
+    bcc?: SmtpAddress[];
+    /** Reply-To address (if different from From) */
+    replyTo?: SmtpAddress;
+    /** Message-ID of the message being replied to (for threading) */
+    inReplyTo?: string;
+    /** Message-ID chain for threading */
+    references?: string[];
+    /** Email subject line */
+    subject: string;
+    /** Plain text body */
+    text?: string;
+    /** HTML body */
+    html?: string;
+    /** Custom Message-ID; auto-generated as <uuid@plot.day> if omitted */
+    messageId?: string;
+};
+/** Result of sending an email. */
+export type SmtpSendResult = {
+    /** The Message-ID that was used (auto-generated or from SmtpMessage) */
+    messageId: string;
+    /** Email addresses that were accepted by the server */
+    accepted: string[];
+    /** Email addresses that were rejected by the server */
+    rejected: string[];
+};
+/**
+ * Built-in tool for SMTP email sending.
+ *
+ * Provides high-level SMTP operations for composing and sending email.
+ * Handles TCP/TLS connections, STARTTLS upgrades, SMTP protocol details,
+ * and RFC 2822 message formatting internally.
+ *
+ * **Permission model:** Connectors declare which SMTP hosts they need access
+ * to. Connections to undeclared hosts are rejected.
+ *
+ * @example
+ * ```typescript
+ * class AppleMailConnector extends Connector<AppleMailConnector> {
+ *   build(build: ConnectorBuilder) {
+ *     return {
+ *       options: build(Options, {
+ *         email: { type: "text", label: "Apple ID Email", default: "" },
+ *         password: { type: "text", label: "App-Specific Password", secure: true, default: "" },
+ *       }),
+ *
+ *       imap: build(Imap, { hosts: ["imap.mail.me.com"] }),
+ *       smtp: build(Smtp, { hosts: ["smtp.mail.me.com"] }),
+ *       integrations: build(Integrations),
+ *     };
+ *   }
+ *
+ *   async sendReply(originalMessage: ImapMessage, replyBody: string) {
+ *     const session = await this.tools.smtp.connect({
+ *       host: "smtp.mail.me.com",
+ *       port: 587,
+ *       tls: false,
+ *       starttls: true,
+ *       username: this.tools.options.email,
+ *       password: this.tools.options.password,
+ *     });
+ *
+ *     try {
+ *       const result = await this.tools.smtp.send(session, {
+ *         from: { address: this.tools.options.email },
+ *         to: originalMessage.from ?? [],
+ *         subject: `Re: ${originalMessage.subject ?? "(no subject)"}`,
+ *         text: replyBody,
+ *         inReplyTo: originalMessage.messageId,
+ *         references: [
+ *           ...(originalMessage.references ?? []),
+ *           ...(originalMessage.messageId ? [originalMessage.messageId] : []),
+ *         ],
+ *       });
+ *
+ *       console.log(`Sent reply, Message-ID: ${result.messageId}`);
+ *     } finally {
+ *       await this.tools.smtp.disconnect(session);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Smtp extends ITool {
+    static readonly Options: {
+        /** SMTP server hostnames this tool is allowed to connect to. */
+        hosts: string[];
+    };
+    /**
+     * Opens a connection to an SMTP server and authenticates.
+     *
+     * Handles the full SMTP handshake: greeting, EHLO, optional STARTTLS
+     * upgrade, and AUTH LOGIN authentication.
+     *
+     * @param options - Server address, port, TLS/STARTTLS setting, and credentials
+     * @returns An opaque session handle for subsequent operations
+     * @throws If the host is not in the declared hosts list, connection fails, or auth fails
+     */
+    abstract connect(options: SmtpConnectOptions): Promise<SmtpSession>;
+    /**
+     * Sends an email message.
+     *
+     * Constructs a properly formatted RFC 2822 message with MIME support
+     * and sends it via the SMTP protocol. Handles multipart messages when
+     * both text and HTML bodies are provided.
+     *
+     * @param session - Session handle from connect()
+     * @param message - The email message to send
+     * @returns Send result with Message-ID and per-recipient acceptance status
+     * @throws If the session is invalid or the server rejects the message entirely
+     */
+    abstract send(session: SmtpSession, message: SmtpMessage): Promise<SmtpSendResult>;
+    /**
+     * Closes the SMTP connection.
+     *
+     * Always call this when done, preferably in a finally block.
+     *
+     * @param session - Session handle from connect()
+     */
+    abstract disconnect(session: SmtpSession): Promise<void>;
+}
+//# sourceMappingURL=smtp.d.ts.map

package/dist/tools/smtp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp.d.ts","sourceRoot":"","sources":["../../src/tools/smtp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE3B,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,GAAG,EAAE,OAAO,CAAC;IACb,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG;IACxB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gCAAgC;AAChC,MAAM,MAAM,WAAW,GAAG;IACxB,qBAAqB;IACrB,IAAI,EAAE,WAAW,CAAC;IAClB,yBAAyB;IACzB,EAAE,EAAE,WAAW,EAAE,CAAC;IAClB,6BAA6B;IAC7B,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;IACnB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG;IAC3B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,8BAAsB,IAAK,SAAQ,KAAK;IACtC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;QACvB,gEAAgE;QAChE,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;IAEF;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAEnE;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,CACX,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CACzD"}

package/dist/tools/smtp.js

@@ -0,0 +1,62 @@
+import { ITool } from "..";
+/**
+ * Built-in tool for SMTP email sending.
+ *
+ * Provides high-level SMTP operations for composing and sending email.
+ * Handles TCP/TLS connections, STARTTLS upgrades, SMTP protocol details,
+ * and RFC 2822 message formatting internally.
+ *
+ * **Permission model:** Connectors declare which SMTP hosts they need access
+ * to. Connections to undeclared hosts are rejected.
+ *
+ * @example
+ * ```typescript
+ * class AppleMailConnector extends Connector<AppleMailConnector> {
+ *   build(build: ConnectorBuilder) {
+ *     return {
+ *       options: build(Options, {
+ *         email: { type: "text", label: "Apple ID Email", default: "" },
+ *         password: { type: "text", label: "App-Specific Password", secure: true, default: "" },
+ *       }),
+ *
+ *       imap: build(Imap, { hosts: ["imap.mail.me.com"] }),
+ *       smtp: build(Smtp, { hosts: ["smtp.mail.me.com"] }),
+ *       integrations: build(Integrations),
+ *     };
+ *   }
+ *
+ *   async sendReply(originalMessage: ImapMessage, replyBody: string) {
+ *     const session = await this.tools.smtp.connect({
+ *       host: "smtp.mail.me.com",
+ *       port: 587,
+ *       tls: false,
+ *       starttls: true,
+ *       username: this.tools.options.email,
+ *       password: this.tools.options.password,
+ *     });
+ *
+ *     try {
+ *       const result = await this.tools.smtp.send(session, {
+ *         from: { address: this.tools.options.email },
+ *         to: originalMessage.from ?? [],
+ *         subject: `Re: ${originalMessage.subject ?? "(no subject)"}`,
+ *         text: replyBody,
+ *         inReplyTo: originalMessage.messageId,
+ *         references: [
+ *           ...(originalMessage.references ?? []),
+ *           ...(originalMessage.messageId ? [originalMessage.messageId] : []),
+ *         ],
+ *       });
+ *
+ *       console.log(`Sent reply, Message-ID: ${result.messageId}`);
+ *     } finally {
+ *       await this.tools.smtp.disconnect(session);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class Smtp extends ITool {
+    static Options;
+}
+//# sourceMappingURL=smtp.js.map

package/dist/tools/smtp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp.js","sourceRoot":"","sources":["../../src/tools/smtp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAiE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,OAAgB,IAAK,SAAQ,KAAK;IACtC,MAAM,CAAU,OAAO,CAGrB;CAuCH"}

package/dist/twist.d.ts

@@ -1,4 +1,4 @@
-import { type Action, type Actor, type ActorId, type Link, type Note, type Priority, type Thread, Uuid } from "./plot";
+import { type Action, type Actor, type ActorId, type Link, type Note, type Thread, Uuid } from "./plot";
 import type { Tag } from "./tag";
 import { type ITool } from "./tool";
 import type { Callback } from "./tools/callbacks";
@@ -7,10 +7,13 @@ import type { InferTools, ToolBuilder, ToolShed } from "./utils/types";
 /**
  * Base class for all twists.
  *
- * Twists are activated in a Plot priority and have access to that priority and all
- * its descendants.
+ * A twist is installed at the workspace level and is owned by a single user
+ * (see `this.userId`). It has no inherent priority scope: threads, notes, and
+ * links it creates are filed against the owner's priorities, with automatic
+ * priority matching when no explicit target is provided.
  *
- * Override build() to declare tool dependencies and lifecycle methods to handle events.
+ * Override `build()` to declare tool dependencies and lifecycle methods to
+ * handle events.
  *
  * @example
  * ```typescript
@@ -21,8 +24,7 @@ import type { InferTools, ToolBuilder, ToolShed } from "./utils/types";
  *     };
  *   }
  *
- *   async activate(priority: Pick<Priority, "id">) {
- *     // Initialize twist for the given priority
+ *   async activate() {
  *     await this.tools.plot.createThread({
  *       title: "Hello, good looking!",
  *     });
@@ -33,6 +35,11 @@ import type { InferTools, ToolBuilder, ToolShed } from "./utils/types";
 export declare abstract class Twist<TSelf> {
     protected id: Uuid;
     private toolShed;
+    /**
+     * The user ID (`twist_instance.owner_id`) that installed this twist.
+     * Populated by the runtime before any lifecycle method runs.
+     */
+    protected userId: Uuid;
     constructor(id: Uuid, toolShed: ToolShed);
     /**
      * Gets the initialized tools for this twist.
@@ -105,7 +112,16 @@ export declare abstract class Twist<TSelf> {
      */
     protected deleteAllCallbacks(): Promise<void>;
     /**
-     * Executes a callback by its token.
+     * Executes a callback by its token inline in the current execution.
+     *
+     * **Use `this.runTask()` instead for batch continuations and long-running work.**
+     * `this.run()` executes inline, sharing the current request count (~1000 limit)
+     * and blocking the HTTP response. This causes timeouts when used in lifecycle
+     * methods like `onChannelEnabled` or `syncBatch` continuations.
+     *
+     * `this.run()` is appropriate when you need the callback's **return value** —
+     * e.g., running a parent callback token that returns data. For fire-and-forget
+     * work, always prefer `this.runTask()`.
      *
      * @param token - The callback token to execute
      * @param args - Optional arguments to pass to the callback
@@ -200,24 +216,25 @@ export declare abstract class Twist<TSelf> {
      */
     protected cancelAllTasks(): Promise<void>;
     /**
-     * Called when the twist is activated for a specific priority.
+     * Called when the twist is installed by a user.
      *
-     * This method should contain initialization logic such as setting up
-     * initial threads, configuring webhooks, or establishing external connections.
+     * This method should contain initialization logic such as seeding
+     * initial threads, configuring webhooks, or establishing external
+     * connections. When it runs, `this.userId` is already populated with
+     * the installing user's ID.
      *
-     * @param priority - The priority context containing the priority ID
      * @param context - Optional context containing the actor who triggered activation
      * @returns Promise that resolves when activation is complete
      */
-    activate(priority: Pick<Priority, "id">, context?: {
+    activate(context?: {
         actor: Actor;
     }): Promise<void>;
     /**
-     * Called when a new version of the twist is deployed to an existing priority.
+     * Called when a new version of the twist is deployed.
      *
      * This method should contain migration logic for updating old data structures
      * or setting up new resources that weren't needed by the previous version.
-     * It is called with the new version for each active priorityTwist.
+     * It is called once per active twist_instance with the new version.
      *
      * @returns Promise that resolves when upgrade is complete
      */
@@ -259,9 +276,14 @@ export declare abstract class Twist<TSelf> {
      *
      * Notes created by the twist itself are filtered out to prevent loops.
      *
+     * Returning a string sets the note's `key` for future upsert matching,
+     * linking the Plot note to its external counterpart so that subsequent
+     * syncs (reactions, edits) update the existing note instead of creating duplicates.
+     *
      * @param note - The newly created note
+     * @returns Optional note key for external deduplication
      */
-    onNoteCreated(note: Note, ...args: any[]): Promise<void>;
+    onNoteCreated(note: Note, ...args: any[]): Promise<string | void>;
     /**
      * Called when a link is created in a connected source channel.
      * Requires `link: true` in Plot options.

package/dist/twist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../src/twist.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../src/twist.ts"],"names":[],"mappings":"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"}