Creating Plot Twists
    Preparing search index...

    Class TwistsAbstract

    Built-in tool for managing twists and deployments.

    The Twists tool provides twists with the ability to create twist IDs and programmatically deploy twists.

    class TwistBuilderTwist extends Twist<TwistBuilderTwist> {
      build(build: ToolBuilder) {
       return {
         twists: build(Twists)
       }
      }

      async activate() {
        const twistId = await this.tools.twists.create();
        // Display twist ID to user
      }
    }

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    create generate deploy watchLogs

    Constructors

    Methods

    • Creates a new twist package ID. Ownership of the ID is claimed lazily on first deploy — no upfront registration happens beyond generating it.

      Returns Promise<string>

      Promise resolving to the generated twist ID

      When twist creation fails

      const twistId = await this.tools.twists.create();
      console.log(`Your twist ID: ${twistId}`);

    • 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).

      Parameters

      • spec: string

        Markdown specification describing the twist functionality

      Returns Promise<TwistSource>

      Promise resolving to twist source (dependencies and files)

      When generation fails after maximum attempts

      const source = await this.tools.twists.generate(`
      # Calendar Sync Twist

      This twist syncs Google Calendar events to Plot threads.

      ## Features
      - Authenticate with Google
      - Sync calendar events
      - Create threads from events
      `);

      // source.dependencies: { "@plotday/twister": "workspace:^", ... }
      // source.files: { "index.ts": "export default class..." }

    • 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

      Parameters

      • options: {
            twistId: string;
            environment?: "personal" | "private" | "review";
            name?: string;
            description?: string;
            dryRun?: boolean;
        } & ({ module: string } | { source: TwistSource })

        Deployment configuration

        • twistId: string

          Twist ID for deployment

        • Optionalenvironment?: "personal" | "private" | "review"

          Target environment (defaults to "personal")

        • Optionalname?: string

          Optional twist name (required for first deploy)

        • Optionaldescription?: string

          Optional twist description (required for first deploy)

        • OptionaldryRun?: boolean

          If true, validates without deploying (returns errors if any)

        • { module: string }
          • module: string

            Pre-bundled twist module code (mutually exclusive with source)

        • { source: TwistSource }
          • source: TwistSource

            Twist source code with dependencies (mutually exclusive with module)

      Returns Promise<{ version: string; permissions: TwistPermissions; errors?: string[] }>

      Promise resolving to deployment result with version and optional errors

      When deployment fails or user lacks access

      // Deploy with a module
      const result = await this.tools.twists.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 this.tools.twists.generate(spec);
      const result = await this.tools.twists.deploy({
        twistId: 'abc-123-...',
        source,
        environment: 'personal',
        name: 'My Twist',
      });

      // Validate with dryRun
      const result = await this.tools.twists.deploy({
        twistId: 'abc-123-...',
        source,
        dryRun: true,
      });
      if (result.errors?.length) {
        console.error('Build errors:', result.errors);
      }

    • 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.

      Parameters

      • twistId: string

        Twist ID (root ID) to watch logs for

      • callback: Callback

        Callback token created via CallbackTool that will receive log batches

      Returns Promise<void>

      Promise that resolves when the subscription is created

      When subscription fails

      // Create twist and callback
      const twistId = await this.tools.twists.create();
      const callback = await this.callback(this.onLogs);

      // Subscribe to logs
      await this.tools.twists.watchLogs(twistId, callback);

      // Implement handler
      async onLogs(logs: Log[]) {
        for (const log of logs) {
          console.log(`[${log.environment}] ${log.severity}: ${log.message}`);
        }
      }

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods