@plotday/twister 0.47.0 → 0.48.0

package/src/tools/smtp.ts

@@ -0,0 +1,166 @@
+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 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>;
+}

package/src/tools/store.ts

@@ -0,0 +1,149 @@
+import { ITool, type Serializable } from "..";
+
+/**
+ * Built-in tool for persistent key-value storage.
+ *
+ * The Store tool provides twists and tools with a simple, persistent storage
+ * mechanism that survives worker restarts and invocations. Each twist/tool
+ * instance gets its own isolated storage namespace.
+ *
+ * **Note:** Store methods are also available directly on Twist and Tool classes
+ * via `this.get()`, `this.set()`, `this.clear()`, and `this.clearAll()`.
+ * This is the recommended approach for most use cases.
+ *
+ * **Storage Characteristics:**
+ * - Persistent across worker restarts
+ * - Isolated per twist/tool instance
+ * - Supports SuperJSON-serializable data (see below)
+ * - Async operations for scalability
+ *
+ * **Supported Data Types (via SuperJSON):**
+ * - Primitives: string, number, boolean, null, undefined
+ * - Complex types: Date, RegExp, Map, Set, Error, URL, BigInt
+ * - Collections: Arrays and objects (recursively)
+ *
+ * **NOT Supported (will throw validation errors):**
+ * - Functions (use callback tokens instead - see Callbacks tool)
+ * - Symbols
+ * - Circular references
+ * - Custom class instances
+ *
+ * **Use Cases:**
+ * - Storing authentication tokens
+ * - Caching configuration data
+ * - Maintaining sync state
+ * - Persisting user preferences
+ * - Tracking processing checkpoints
+ *
+ * @example
+ * ```typescript
+ * class CalendarTool extends Tool {
+ *   async saveAuthToken(provider: string, token: string) {
+ *     // Using built-in set method (recommended)
+ *     await this.set(`auth_token_${provider}`, token);
+ *   }
+ *
+ *   async getAuthToken(provider: string): Promise<string | null> {
+ *     // Using built-in get method (recommended)
+ *     return await this.get<string>(`auth_token_${provider}`);
+ *   }
+ *
+ *   async clearAllTokens() {
+ *     // Using built-in clearAll method (recommended)
+ *     await this.clearAll();
+ *   }
+ * }
+ * ```
+ */
+export abstract class Store extends ITool {
+  /**
+   * Retrieves a value from storage by key.
+   *
+   * Returns the stored value deserialized to the specified type,
+   * or null if the key doesn't exist or the value is null.
+   *
+   * Values are automatically deserialized using SuperJSON, which
+   * properly restores Date objects, Maps, Sets, and other complex types.
+   *
+   * @template T - The expected type of the stored value (must be Serializable)
+   * @param key - The storage key to retrieve
+   * @returns Promise resolving to the stored value or null
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract get<T extends Serializable>(key: string): Promise<T | null>;
+
+  /**
+   * Stores a value in persistent storage.
+   *
+   * The value will be serialized using SuperJSON and stored persistently.
+   * Any existing value at the same key will be overwritten.
+   *
+   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+   * and other complex types that standard JSON doesn't support.
+   *
+   * @template T - The type of value being stored (must be Serializable)
+   * @param key - The storage key to use
+   * @param value - The value to store (must be SuperJSON-serializable)
+   * @returns Promise that resolves when the value is stored
+   *
+   * @example
+   * ```typescript
+   * // Date objects are preserved
+   * await this.set('sync_state', {
+   *   lastSync: new Date(),
+   *   minDate: new Date(2024, 0, 1)
+   * });
+   *
+   * // undefined is now supported
+   * await this.set('data', { name: 'test', optional: undefined }); // ✅ Works
+   *
+   * // Arrays with undefined are supported
+   * await this.set('items', [1, undefined, 3]); // ✅ Works
+   * await this.set('items', [1, null, 3]); // ✅ Also works
+   *
+   * // Maps and Sets are supported
+   * await this.set('mapping', new Map([['key', 'value']])); // ✅ Works
+   * await this.set('tags', new Set(['tag1', 'tag2'])); // ✅ Works
+   *
+   * // Functions are NOT supported - use callback tokens instead
+   * const token = await this.callback(this.myFunction);
+   * await this.set('callback_ref', token); // ✅ Use callback token
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract set<T extends Serializable>(key: string, value: T): Promise<void>;
+
+  /**
+   * Lists all storage keys matching a prefix.
+   *
+   * Returns an array of key strings that start with the given prefix.
+   * Useful for finding all keys in a namespace (e.g., all sync locks).
+   *
+   * @param prefix - The prefix to match keys against
+   * @returns Promise resolving to an array of matching key strings
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract list(prefix: string): Promise<string[]>;
+
+  /**
+   * Removes a specific key from storage.
+   *
+   * After this operation, get() calls for this key will return null.
+   * No error is thrown if the key doesn't exist.
+   *
+   * @param key - The storage key to remove
+   * @returns Promise that resolves when the key is removed
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract clear(key: string): Promise<void>;
+
+  /**
+   * Removes all keys from this storage instance.
+   *
+   * This operation clears all data stored by this twist/tool instance
+   * but does not affect storage for other twists or tools.
+   *
+   * @returns Promise that resolves when all keys are removed
+   */
+  abstract clearAll(): Promise<void>;
+}

package/src/tools/tasks.ts

@@ -0,0 +1,137 @@
+import { ITool } from "..";
+import type { Callback } from "./callbacks";
+
+/**
+ * Run background tasks and scheduled jobs.
+ *
+ * The Tasks tool enables twists and tools to queue callbacks for execution in separate
+ * worker contexts. **This is critical for staying under request limits**: each execution
+ * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and
+ * running a task creates a NEW execution with a fresh request limit.
+ *
+ * **Key distinction:**
+ * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count
+ * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit
+ *
+ * **When to use tasks:**
+ * - Processing large datasets that would exceed 1000 requests
+ * - Breaking loops into chunks where each chunk stays under the request limit
+ * - Scheduling operations for future execution
+ *
+ * **Note:** Tasks tool methods are also available directly on Twist and Tool classes
+ * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.
+ * This is the recommended approach for most use cases.
+ *
+ * **Best Practices:**
+ * - Size batches to stay under ~1000 requests per execution
+ * - Calculate requests per item to determine safe batch size
+ * - Create callbacks first using `this.callback()`
+ * - Store intermediate state using the Store tool
+ *
+ * @example
+ * ```typescript
+ * class SyncTool extends Tool {
+ *   async startBatchSync(totalItems: number) {
+ *     // Store initial state using built-in set method
+ *     await this.set("sync_progress", { processed: 0, total: totalItems });
+ *
+ *     // Create callback and queue first batch
+ *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     // runTask creates NEW execution with fresh ~1000 request limit
+ *     await this.runTask(callback);
+ *   }
+ *
+ *   async processBatch(args: any, context: { batchNumber: number }) {
+ *     // Process one batch of items (sized to stay under request limit)
+ *     const progress = await this.get("sync_progress");
+ *
+ *     // If each item makes ~10 requests, process ~100 items per batch
+ *     // 100 items × 10 requests = 1000 requests (at limit)
+ *     const batchSize = 100;
+ *     const items = await this.fetchItems(progress.processed, batchSize);
+ *
+ *     for (const item of items) {
+ *       await this.processItem(item); // Makes ~10 requests per item
+ *     }
+ *
+ *     await this.set("sync_progress", {
+ *       processed: progress.processed + batchSize,
+ *       total: progress.total
+ *     });
+ *
+ *     if (progress.processed < progress.total) {
+ *       // Queue next batch - creates NEW execution with fresh request limit
+ *       const callback = await this.callback("processBatch", {
+ *         batchNumber: context.batchNumber + 1
+ *       });
+ *       await this.runTask(callback);
+ *     }
+ *   }
+ *
+ *   async scheduleCleanup() {
+ *     const tomorrow = new Date();
+ *     tomorrow.setDate(tomorrow.getDate() + 1);
+ *
+ *     const callback = await this.callback("cleanupOldData");
+ *     // Schedule for future execution
+ *     return await this.runTask(callback, { runAt: tomorrow });
+ *   }
+ * }
+ * ```
+ */
+export abstract class Tasks extends ITool {
+  /**
+   * Queues a callback to execute in a separate worker context with a fresh request limit.
+   *
+   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,
+   * tool calls, database operations). This is the primary way to stay under request limits
+   * when processing large datasets or making many API calls.
+   *
+   * The callback will be invoked either immediately or at a scheduled time
+   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds
+   * CPU time. Use this for breaking loops into chunks that stay under the request limit.
+   *
+   * **Key distinction:**
+   * - `this.run(callback)` - Continues same execution, shares request count
+   * - `this.runTask(callback)` - NEW execution, fresh request limit
+   *
+   * @param callback - Callback created with `this.callback()`
+   * @param options - Optional configuration for the execution
+   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately
+   * @returns Promise resolving to a cancellation token (only for scheduled executions)
+   *
+   * @example
+   * ```typescript
+   * // Break large loop into batches to stay under request limit
+   * const callback = await this.callback("syncBatch", { page: 1 });
+   * await this.runTask(callback); // Fresh execution with ~1000 requests
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract runTask(
+    callback: Callback,
+    options?: { runAt?: Date }
+  ): Promise<string | void>;
+
+  /**
+   * Cancels a previously scheduled execution.
+   *
+   * Prevents a scheduled function from executing. No error is thrown
+   * if the token is invalid or the execution has already completed.
+   *
+   * @param token - The cancellation token returned by runTask() with runAt option
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract cancelTask(token: string): Promise<void>;
+
+  /**
+   * Cancels all scheduled executions for this tool/twist.
+   *
+   * Cancels all pending scheduled executions created by this tool or twist
+   * instance. Immediate executions cannot be cancelled.
+   *
+   * @returns Promise that resolves when all cancellations are processed
+   */
+  abstract cancelAllTasks(): Promise<void>;
+}

package/src/tools/twists.ts

@@ -0,0 +1,228 @@
+import { type Callback, ITool } from "..";
+
+/**
+ * Twist source code structure containing dependencies and source files.
+ */
+export interface TwistSource {
+  /**
+   * Package dependencies with version specifiers
+   * @example { "@plotday/twister": "workspace:^", "@plotday/tool-google-calendar": "^1.0.0" }
+   */
+  dependencies: Record<string, string>;
+
+  /**
+   * Source files with their content
+   * Must include "index.ts" as the entry point
+   * @example { "index.ts": "export default class MyTwist extends Twist {...}" }
+   */
+  files: Record<string, string>;
+}
+
+/**
+ * Represents a log entry from a twist execution.
+ */
+export type Log = {
+  timestamp: Date;
+  environment: "personal" | "private" | "review" | "public";
+  severity: "log" | "error" | "warn" | "info";
+  message: string;
+};
+
+/**
+ * Twist permissions returned after deployment.
+ * Nested structure mapping domains to entities to permission flags.
+ *
+ * Format: { domain: { entity: flags[] } }
+ * - domain: Tool name (e.g., "network", "plot")
+ * - entity: Domain-specific identifier (e.g., URL pattern, resource type)
+ * - flags: Array of permission flags ("read", "write", "update", "use")
+ *
+ * @example
+ * ```typescript
+ * {
+ *   "network": {
+ *     "https://api.example.com/*": ["use"],
+ *     "https://googleapis.com/*": ["use"]
+ *   },
+ *   "plot": {
+ *     "thread:mentioned": ["read", "write", "update"],
+ *     "priority": ["read", "write", "update"]
+ *   }
+ * }
+ * ```
+ */
+export type TwistPermissions = Record<string, Record<string, string[]>>;
+
+/**
+ * Built-in tool for managing twists and deployments.
+ *
+ * The Twists tool provides twists with the ability to create twist IDs
+ * and programmatically deploy twists.
+ *
+ * @example
+ * ```typescript
+ * class TwistBuilderTwist extends Twist {
+ *   build(build: ToolBuilder) {
+ *    return {
+ *      twists: build.get(Twists)
+ *    }
+ *   }
+ *
+ *   async activate() {
+ *     const twistId = await this.tools.twists.create();
+ *     // Display twist ID to user
+ *   }
+ * }
+ * ```
+ */
+export abstract class Twists extends ITool {
+  /**
+   * Creates a new twist ID and grants access to people in the current priority.
+   *
+   * @returns Promise resolving to the generated twist ID
+   * @throws When twist creation fails
+   *
+   * @example
+   * ```typescript
+   * const twistId = await twist.create();
+   * console.log(`Your twist ID: ${twistId}`);
+   * ```
+   */
+  abstract create(): Promise<string>;
+
+  /**
+   * Generates twist source code from a specification using AI.
+   *
+   * This method uses Claude AI to generate TypeScript source code and dependencies
+   * from a markdown specification. The generated source is validated by attempting
+   * to build it, with iterative error correction (up to 3 attempts).
+   *
+   * @param spec - Markdown specification describing the twist functionality
+   * @returns Promise resolving to twist source (dependencies and files)
+   * @throws When generation fails after maximum attempts
+   *
+   * @example
+   * ```typescript
+   * const source = await twist.generate(`
+   * # Calendar Sync Twist
+   *
+   * This twist syncs Google Calendar events to Plot activities.
+   *
+   * ## Features
+   * - Authenticate with Google
+   * - Sync calendar events
+   * - Create activities from events
+   * `);
+   *
+   * // source.dependencies: { "@plotday/twister": "workspace:^", ... }
+   * // source.files: { "index.ts": "export default class..." }
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract generate(spec: string): Promise<TwistSource>;
+
+  /**
+   * Deploys a twist programmatically.
+   *
+   * This method provides the same functionality as the plot deploy CLI
+   * command, but can be called from within a twist. Accepts either:
+   * - A pre-bundled module (JavaScript code)
+   * - A source object (dependencies + files) which is built in a sandbox
+   *
+   * @param options - Deployment configuration
+   * @param options.twistId - Twist ID for deployment
+   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)
+   * @param options.source - Twist source code with dependencies (mutually exclusive with module)
+   * @param options.environment - Target environment (defaults to "personal")
+   * @param options.name - Optional twist name (required for first deploy)
+   * @param options.description - Optional twist description (required for first deploy)
+   * @param options.dryRun - If true, validates without deploying (returns errors if any)
+   * @returns Promise resolving to deployment result with version and optional errors
+   * @throws When deployment fails or user lacks access
+   *
+   * @example
+   * ```typescript
+   * // Deploy with a module
+   * const result = await twist.deploy({
+   *   twistId: 'abc-123-...',
+   *   module: 'export default class MyTwist extends Twist {...}',
+   *   environment: 'personal',
+   *   name: 'My Twist',
+   *   description: 'Does something cool'
+   * });
+   * console.log(`Deployed version ${result.version}`);
+   *
+   * // Deploy with source
+   * const source = await twist.generate(spec);
+   * const result = await twist.deploy({
+   *   twistId: 'abc-123-...',
+   *   source,
+   *   environment: 'personal',
+   *   name: 'My Twist',
+   * });
+   *
+   * // Validate with dryRun
+   * const result = await twist.deploy({
+   *   twistId: 'abc-123-...',
+   *   source,
+   *   dryRun: true,
+   * });
+   * if (result.errors?.length) {
+   *   console.error('Build errors:', result.errors);
+   * }
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract deploy(
+    options: {
+      twistId: string;
+      environment?: "personal" | "private" | "review";
+      name?: string;
+      description?: string;
+      dryRun?: boolean;
+    } & (
+      | {
+          module: string;
+        }
+      | {
+          source: TwistSource;
+        }
+    )
+  ): Promise<{
+    version: string;
+    permissions: TwistPermissions;
+    errors?: string[];
+  }>;
+
+  /**
+   * Subscribes to logs from a twist.
+   *
+   * This method registers a callback to receive batches of logs from twist executions.
+   * The callback will be invoked with an array of logs whenever new logs are captured
+   * from the twist's console output.
+   *
+   * @param twistId - Twist ID (root ID) to watch logs for
+   * @param callback - Callback token created via CallbackTool that will receive log batches
+   * @returns Promise that resolves when the subscription is created
+   * @throws When subscription fails
+   *
+   * @example
+   * ```typescript
+   * // Create twist and callback
+   * const twistId = await this.twist.create();
+   * const callback = await this.callback.create("onLogs");
+   *
+   * // Subscribe to logs
+   * await this.twist.watchLogs(twistId, callback);
+   *
+   * // Implement handler
+   * async onLogs(logs: Log[]) {
+   *   for (const log of logs) {
+   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);
+   *   }
+   * }
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;
+}

package/src/twist-guide.ts

@@ -0,0 +1,9 @@
+/**
+ * Twist Implementation Guide
+ *
+ * This guide is used by AI systems to generate Plot twists.
+ * Auto-generated from cli/templates/AGENTS.template.md during build.
+ */
+import twistsGuideTemplate from "./llm-docs/twist-guide-template.js";
+
+export const TWIST_GUIDE = twistsGuideTemplate;