@plotday/twister 0.20.0

package/dist/tools/store.d.ts

@@ -0,0 +1,90 @@
+import { ITool } 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 any JSON-serializable data
+ * - Async operations for scalability
+ *
+ * **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 declare 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.
+     *
+     * @template T - The expected type of the stored value
+     * @param key - The storage key to retrieve
+     * @returns Promise resolving to the stored value or null
+     */
+    abstract get<T>(key: string): Promise<T | null>;
+    /**
+     * Stores a value in persistent storage.
+     *
+     * The value will be JSON-serialized and stored persistently.
+     * Any existing value at the same key will be overwritten.
+     *
+     * @template T - The type of value being stored
+     * @param key - The storage key to use
+     * @param value - The value to store (must be JSON-serializable)
+     * @returns Promise that resolves when the value is stored
+     */
+    abstract set<T>(key: string, value: T): Promise<void>;
+    /**
+     * 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
+     */
+    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>;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/tools/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,8BAAsB,KAAM,SAAQ,KAAK;IACvC;;;;;;;;;OASG;IAEH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;OAUG;IAEH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAErD;;;;;;;;OAQG;IAEH,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CACnC"}

package/dist/tools/store.js

@@ -0,0 +1,48 @@
+import { ITool } 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 any JSON-serializable data
+ * - Async operations for scalability
+ *
+ * **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 class Store extends ITool {
+}
+//# sourceMappingURL=store.js.map

package/dist/tools/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/tools/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAgB,KAAM,SAAQ,KAAK;CAiDxC"}

package/dist/tools/tasks.d.ts

@@ -0,0 +1,93 @@
+import { ITool } from "..";
+import type { Callback } from "./callbacks";
+/**
+ * Run background tasks and scheduled jobs.
+ *
+ * The Run tool enables twists and tools to queue callbacks. This is especially
+ * iportant for long-running operations and batch processing, since twists
+ * operate within runtime limits. Run callbacks also benefit from automatic
+ * retries on failure.
+ *
+ * **Note:** Run 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:**
+ * - Break long operations into smaller batches
+ * - 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 using built-in methods
+ *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     await this.runTask(callback);
+ *   }
+ *
+ *   async processBatch(args: any, context: { batchNumber: number }) {
+ *     // Process one batch of items
+ *     const progress = await this.get("sync_progress");
+ *
+ *     // ... process items ...
+ *
+ *     if (progress.processed < progress.total) {
+ *       // Queue next batch using built-in methods
+ *       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");
+ *     return await this.run(callback, { runAt: tomorrow });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Tasks extends ITool {
+    /**
+     * Queues a callback to execute in a separate worker context.
+     *
+     * The callback will be invoked either immediately or at a scheduled time
+     * in an isolated execution environment with limited resources. Use this
+     * for breaking up long-running operations into manageable chunks.
+     *
+     * @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)
+     */
+    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
+     */
+    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>;
+}
+//# sourceMappingURL=tasks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,8BAAsB,KAAM,SAAQ,KAAK;IACvC;;;;;;;;;;;OAWG;IAEH,QAAQ,CAAC,OAAO,CACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,IAAI,CAAA;KAAE,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;;OAQG;IAEH,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjD;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CACzC"}

package/dist/tools/tasks.js

@@ -0,0 +1,58 @@
+import { ITool } from "..";
+/**
+ * Run background tasks and scheduled jobs.
+ *
+ * The Run tool enables twists and tools to queue callbacks. This is especially
+ * iportant for long-running operations and batch processing, since twists
+ * operate within runtime limits. Run callbacks also benefit from automatic
+ * retries on failure.
+ *
+ * **Note:** Run 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:**
+ * - Break long operations into smaller batches
+ * - 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 using built-in methods
+ *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     await this.runTask(callback);
+ *   }
+ *
+ *   async processBatch(args: any, context: { batchNumber: number }) {
+ *     // Process one batch of items
+ *     const progress = await this.get("sync_progress");
+ *
+ *     // ... process items ...
+ *
+ *     if (progress.processed < progress.total) {
+ *       // Queue next batch using built-in methods
+ *       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");
+ *     return await this.run(callback, { runAt: tomorrow });
+ *   }
+ * }
+ * ```
+ */
+export class Tasks extends ITool {
+}
+//# sourceMappingURL=tasks.js.map

package/dist/tools/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAG3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,OAAgB,KAAM,SAAQ,KAAK;CAwCxC"}

package/dist/tools/twists.d.ts

@@ -0,0 +1,213 @@
+import { type Callback, ITool } from "..";
+/**
+ * Twist source code structure containing dependencies and source files.
+ */
+export interface TwistSource {
+    /**
+     * Package dependencies with version specifiers
+     * @example { "@plotday/sdk": "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": {
+ *     "activity: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 declare 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/sdk": "workspace:^", ... }
+     * // source.files: { "index.ts": "export default class..." }
+     * ```
+     */
+    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);
+     * }
+     * ```
+     */
+    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}`);
+     *   }
+     * }
+     * ```
+     */
+    abstract watchLogs(twistId: string, callback: Callback): Promise<void>;
+}
+//# sourceMappingURL=twists.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"twists.d.ts","sourceRoot":"","sources":["../../src/tools/twists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1D,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,MAAO,SAAQ,KAAK;IACxC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IAEH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IAEH,QAAQ,CAAC,MAAM,CACb,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;QAChD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,CACA;QACE,MAAM,EAAE,MAAM,CAAC;KAChB,GACD;QACE,MAAM,EAAE,WAAW,CAAC;KACrB,CACJ,GACA,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IAEH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CACvE"}

package/dist/tools/twists.js

@@ -0,0 +1,26 @@
+import { ITool } from "..";
+/**
+ * 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 class Twists extends ITool {
+}
+//# sourceMappingURL=twists.js.map

package/dist/tools/twists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twists.js","sourceRoot":"","sources":["../../src/tools/twists.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,EAAE,MAAM,IAAI,CAAC;AAuD1C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAgB,MAAO,SAAQ,KAAK;CAsJzC"}

package/dist/twist-guide.d.ts

@@ -0,0 +1,2 @@
+export declare const TWIST_GUIDE = "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  twist,\n  type Priority,\n  type ToolBuilder,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\n\nexport default class MyTwist extends twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Task,\n    title: \"Connect your account\",\n    links: [authLink],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Task,\n  title: \"Setup\",\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity\nawait this.tools.plot.createActivity({\n  type: ActivityType.Task,\n  title: \"Task with links\",\n  links: [urlLink, callbackLink],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Task,\n    title: \"Connect Google account\",\n    links: [authLink],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data with callbacks:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(activity: Activity, calendarId: string): Promise<void> {\n  // Process incoming event from external service\n  await this.tools.plot.createActivity(activity);\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `\uD83D\uDCC5 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    links,\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results\n  for (const item of result.items) {\n    await this.tools.plot.createActivity(item);\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      note: `Sync complete: ${state.itemsProcessed + result.items.length} items processed`,\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    note: `Failed to complete operation: ${error.message}`,\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- Most activity should be `type = ActivityType.Note` with a `title` and `note`, and no `start` or `end`. This represents a typical message. `start` and `end` should only be used for a note if it should be displayed for a specific date or time, such as a birthday.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+//# sourceMappingURL=twist-guide.d.ts.map

package/dist/twist-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twist-guide.d.ts","sourceRoot":"","sources":["../src/twist-guide.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,onZAAsB,CAAC"}

package/dist/twist-guide.js

@@ -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;
+//# sourceMappingURL=twist-guide.js.map

package/dist/twist-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twist-guide.js","sourceRoot":"","sources":["../src/twist-guide.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,mBAAmB,MAAM,oCAAoC,CAAC;AAErE,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC"}