@plotday/twister 0.60.0 → 0.61.0

package/src/plot.ts

@@ -655,6 +655,32 @@ export type ThreadUpdate =
  * Notes contain the detailed content (note text, actions) associated with a thread.
  * They are always ordered by creation time within their parent thread.
  */
+/**
+ * Reports that an outbound send / write-back for a note could not be
+ * delivered to the external system, so Plot can surface it to the user.
+ *
+ * Returned (not thrown) from a write-back hook — see
+ * `NoteWriteBackResult.deliveryError` and `NewLinkWithNotes.originatingNote` —
+ * after the connector has exhausted its own retries (or immediately for a
+ * permanent failure such as a rejected recipient). The runtime records it on
+ * the note (the app then shows a "Failed to send" affordance with Retry /
+ * Discard) and marks the thread unread so the user notices.
+ */
+export type DeliveryError = {
+  /**
+   * Short, stable machine code for the failure category, e.g. `"rejected"`,
+   * `"too_large"`, `"rate_limited"`, `"invalid_recipient"`, or the generic
+   * `"send_failed"`. Used for logging/diagnostics, not shown verbatim to users.
+   */
+  code: string;
+  /**
+   * Human-readable, user-safe explanation to show beside "Failed to send"
+   * (e.g. "Recipient address rejected"). Null/omitted when the connector has
+   * no safe message to surface — the app then shows just "Failed to send".
+   */
+  message?: string | null;
+};
+
 export type Note = ThreadCommon & {
   /** The author of this note */
   author: Actor;
@@ -1141,8 +1167,51 @@ export type NewLink = Partial<
      * an event vs a subscribed copy) so clients display it as the primary.
      */
     priority?: number;
+    /**
+     * Opt this message into the platform's sequential auto-threading. When a
+     * connection has auto-threading enabled, the runtime decides — once,
+     * globally, at ingest — whether this message starts a new thread or folds
+     * (as a note) into the thread of the conversation it continues. Set it on
+     * every message of a conversational surface (a chat channel, a DM); the
+     * runtime keys the sequential chain on {@link AutoThreadConfig.key}.
+     *
+     * Marking a link is a no-op unless the connection opted in, so connectors
+     * can set it unconditionally on eligible links. Leave undefined/null for
+     * non-conversational items (issues, events, files). See
+     * {@link Connector.autoThreading}.
+     */
+    autoThread?: AutoThreadConfig | null;
   };
 
+/**
+ * How the runtime groups a connector's messages into threads when
+ * auto-threading is enabled for the connection.
+ *
+ * - `"sequential"`: a chat **channel**. Each message either continues the
+ *   previous message's conversation (folds in as a note) or starts a new
+ *   thread, decided by a high-confidence continuation check. Use for
+ *   multi-participant channels where consecutive top-level messages often
+ *   form one conversation.
+ * - `"fold"`: a **DM** / one-to-one surface. Every message folds into a
+ *   single running thread for that {@link AutoThreadConfig.key} (no per-message
+ *   judgment). Use for direct messages, which read naturally as one continuous
+ *   conversation.
+ */
+export type AutoThreadMode = "sequential" | "fold";
+
+/** Per-link auto-threading directive. See {@link NewLink.autoThread}. */
+export type AutoThreadConfig = {
+  /**
+   * The conversation grouping the sequential chain runs within — typically the
+   * connector's channel id ({@link Link.channelId}). DMs and each channel form
+   * independent chains. Messages are only ever folded into another message
+   * that shares this key.
+   */
+  key: string;
+  /** Channel (`"sequential"`) vs DM (`"fold"`) grouping. */
+  mode: AutoThreadMode;
+};
+
 /**
  * A new link with notes to save via integrations.saveLink().
  * Creates a thread+link pair, with notes attached to the thread.
@@ -1180,6 +1249,17 @@ export type NewLinkWithNotes = NewLink & {
      * `content` on re-ingest (same contract as `NoteWriteBackResult.externalContent`).
      */
     externalContent?: string;
+    /**
+     * Reports that sending the composed message FAILED (the `onCreateLink`
+     * send could not be delivered). The runtime records it on the opening
+     * note — surfacing a "Failed to send" affordance (Retry / Discard) — and
+     * marks the thread unread. Same contract as
+     * `NoteWriteBackResult.deliveryError`: object records, `null` clears,
+     * omitted leaves untouched. Return the link anyway (so the user's composed
+     * content is preserved in Plot) with this set, rather than returning
+     * `null`, when a compose send fails.
+     */
+    deliveryError?: DeliveryError | null;
   };
 };
 

package/src/tool.ts

@@ -287,6 +287,39 @@ export abstract class Tool<TSelf> implements ITool {
     return this.tools.tasks.cancelAllTasks();
   }
 
+  /**
+   * Schedules a **singleton** task keyed by `key`: re-scheduling under the same
+   * key atomically replaces any pending task, so at most one is ever live.
+   *
+   * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs
+   * (watch renewals, polling, deferred cleanup) — it removes the error-prone
+   * "store token, cancel before re-scheduling" bookkeeping that otherwise leaks
+   * parallel task chains. See {@link Tasks.scheduleTask}.
+   *
+   * @param key - Stable identifier scoped to what the task renews
+   * @param callback - The callback token created with `this.callback()`
+   * @param options.runAt - When to run (required)
+   * @returns Promise resolving to the scheduled task's cancellation token
+   */
+  protected async scheduleTask(
+    key: string,
+    callback: Callback,
+    options: { runAt: Date }
+  ): Promise<string | void> {
+    return this.tools.tasks.scheduleTask(key, callback, options);
+  }
+
+  /**
+   * Cancels the singleton task previously scheduled under `key` (if any).
+   * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.
+   *
+   * @param key - The same key passed to {@link scheduleTask}
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  protected async cancelScheduledTask(key: string): Promise<void> {
+    return this.tools.tasks.cancelScheduledTask(key);
+  }
+
   /**
    * Called before the twist's activate method, starting from the deepest tool dependencies.
    *

package/src/tools/tasks.ts

@@ -132,4 +132,56 @@ export abstract class Tasks extends ITool {
    * @returns Promise that resolves when all cancellations are processed
    */
   abstract cancelAllTasks(): Promise<void>;
+
+  /**
+   * Schedules a **singleton** task identified by `key`: scheduling under a key
+   * that already has a pending task atomically cancels the existing one and
+   * replaces it. At most one scheduled task per `key` is ever live.
+   *
+   * Use this for any recurring/self-renewing job — webhook/watch renewals,
+   * periodic polling, deferred cleanup — instead of hand-managing tokens with
+   * `runTask()` + `cancelTask()`. The manual pattern (store the token, cancel
+   * it before re-scheduling) is easy to get wrong: a renewal callback that
+   * re-schedules itself, combined with any *extra* scheduling call (a
+   * re-dispatched `onChannelEnabled`, a re-init), leaks parallel self-
+   * perpetuating chains that accumulate forever and can trip the runtime's
+   * execution quota. Keying makes that leak impossible by construction.
+   *
+   * Replacement is atomic on the server, so concurrent executions racing to
+   * schedule the same key converge on a single task rather than leaking.
+   *
+   * @param key - Stable identifier for this logical task. Scope it to what it
+   *   renews, e.g. `` `watch-renewal:${folderId}` ``.
+   * @param callback - Callback created with `this.callback()`
+   * @param options.runAt - When to run. Required: keying only applies to
+   *   scheduled tasks (immediate tasks go straight to the queue).
+   * @returns Promise resolving to the cancellation token for the scheduled task
+   *
+   * @example
+   * ```typescript
+   * const cb = await this.callback(this.renewWatch, folderId);
+   * await this.scheduleTask(`watch-renewal:${folderId}`, cb, { runAt });
+   * // ...later, on disable:
+   * await this.cancelScheduledTask(`watch-renewal:${folderId}`);
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract scheduleTask(
+    key: string,
+    callback: Callback,
+    options: { runAt: Date }
+  ): Promise<string | void>;
+
+  /**
+   * Cancels the singleton task previously scheduled under `key` (if any).
+   *
+   * No error is thrown if no task exists for the key or it has already run.
+   * Pair this with {@link scheduleTask} in teardown paths (e.g.
+   * `onChannelDisabled`, `stopSync`).
+   *
+   * @param key - The same key passed to {@link scheduleTask}
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract cancelScheduledTask(key: string): Promise<void>;
 }

package/src/twist.ts

@@ -294,6 +294,39 @@ export abstract class Twist<TSelf> {
     return this.tools.tasks.cancelAllTasks();
   }
 
+  /**
+   * Schedules a **singleton** task keyed by `key`: re-scheduling under the same
+   * key atomically replaces any pending task, so at most one is ever live.
+   *
+   * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs
+   * (watch renewals, polling, deferred cleanup) — it removes the error-prone
+   * "store token, cancel before re-scheduling" bookkeeping that otherwise leaks
+   * parallel task chains. See {@link Tasks.scheduleTask}.
+   *
+   * @param key - Stable identifier scoped to what the task renews
+   * @param callback - The callback token created with `this.callback()`
+   * @param options.runAt - When to run (required)
+   * @returns Promise resolving to the scheduled task's cancellation token
+   */
+  protected async scheduleTask(
+    key: string,
+    callback: Callback,
+    options: { runAt: Date }
+  ): Promise<string | void> {
+    return this.tools.tasks.scheduleTask(key, callback, options);
+  }
+
+  /**
+   * Cancels the singleton task previously scheduled under `key` (if any).
+   * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.
+   *
+   * @param key - The same key passed to {@link scheduleTask}
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  protected async cancelScheduledTask(key: string): Promise<void> {
+    return this.tools.tasks.cancelScheduledTask(key);
+  }
+
   /**
    * Called when the twist is installed by a user.
    *