Blueprints & Plugins

Blueprints are pre-built, configurable workflow actions that can be added to any workflow from the Plugin Catalog. Each blueprint provides a guided wizard to collect configuration values, then generates the underlying V8 script automatically. Blueprints are stored as inline nodes directly on the workflow JSON — they do not require a separate Workflow Entity in the database.

Plugin Catalog

The Plugin Catalog is accessible from the workflow canvas:

Sidebar panel — click the plugin icon in the left sidebar to browse all available plugins
Right-click context menu — right-click on a node and select "Plugins" to open the catalog

Plugins are organized by category and searchable. Each card shows the plugin name, description, and category badge.

Available Plugins

Plugin	Category	Description
Post to Mastodon	Social	Post a status update to a Mastodon server
Post Latest Prompt to Mastodon	Social	Post the most recent AI prompt response to Mastodon
Send Email	Email	Send an email via the SendGrid API
Store to Memory	Storage	Store a value to short-term memory (S3) for later retrieval
Retrieve from Memory	Storage	Retrieve a value from short-term memory (S3)
Publish to Channel	Data	Publish a message to a Redis pub/sub channel for real-time delivery
Shopify Worst Sellers	Shopify	Fetch active products and rank by lowest sales
HTTP Request	Communications	Make a single HTTP request (GET, POST, PUT, DELETE, PATCH, OPTIONS)
HTTP Stream	Communications	Open a long-lived HTTP streaming connection

Blueprint Wizard

When you select a plugin from the catalog, a multi-step wizard guides you through configuration. Each step contains one or more fields that map to script parameters.

Wizard Field Types

Field Type	Rendered As	Description
`text`	Text input	Static string value or environment variable name
`textarea`	Multi-line input	Larger text content (e.g., email body)
`select`	Dropdown	Choose from predefined options
`variable-picker`	Identifier / variable input	Reference a V8 global variable or expression
`json`	JSON editor (Monaco)	JSON object or expression with syntax highlighting
`boolean`	Checkbox	True/false toggle
`template`	Template editor	Jinja2/Nunjucks template with `{{ variable }}` interpolation

Identifier vs. String Mode

Many fields support toggling between identifier mode (references a variable by name, e.g., payload.email) and string mode (a literal value, e.g., "user@example.com"). Click the mode toggle icon on any field to switch.

Validation

Fields include client-side validation rules: required fields, string minimums, regex patterns, and valid JavaScript identifiers. The wizard highlights errors before you can proceed to the next step.

Required Variables

Some plugins require environment variables to be configured at the organization level. The wizard shows these requirements and links to setup documentation. For example:

Mastodon requires MASTODON_URL and MASTODON_ACCESS_TOKEN
SendGrid requires SENDGRID_API_KEY
Shopify requires SHOPIFY_STORE_DOMAIN and SHOPIFY_ACCESS_TOKEN
HTTP Request/Stream — API keys are optional but commonly used

Inline Blueprint Nodes

When a blueprint is applied, the workflow canvas creates an inline node. Unlike standard Workflow Entity nodes that reference a database entity by ID, inline nodes carry their configuration directly on the workflow JSON:

{
  "ref": "node-abc123",
  "entityType": "action",
  "name": "HTTP Request",
  "blueprintSlug": "http-request",
  "blueprintVersion": 1,
  "blueprintValues": {
    "url": "https://api.example.com/v1/data",
    "method": "GET",
    "apiKey": "MY_API_KEY",
    "apiKeyHeader": "x-api-key",
    "followRedirects": true,
    "body": null
  },
  "preScript": "const result = await httpRequest({\n  url: \"https://api.example.com/v1/data\",\n  method: \"GET\",\n  apiKey: MY_API_KEY,\n  apiKeyHeader: \"x-api-key\",\n  followRedirects: true,\n  body: null,\n});\nprint(\"HTTP\", result.status, \"GET\", \"https://api.example.com/v1/data\");",
  "postScript": null,
  "children": [...]
}

Key Fields

Field	Type	Description
`blueprintSlug`	`string`	Identifies which blueprint created this node (e.g., `"http-request"`, `"sendgrid-email"`)
`blueprintVersion`	`number`	Blueprint version number for upgrade tracking
`blueprintValues`	`object`	The wizard field values used to generate the script
`preScript`	`string`	The generated V8 script that runs during execution
`postScript`	`string \| null`	Optional post-execution script

No Database Entity Required

Inline nodes do not have an entityId. The workflow engine generates a synthetic entity ID (inline-<ref>) at runtime. This means:

No WFE row — the node's script lives in the workflow JSON, not in the WorkflowEntity table
Self-contained — copying or exporting a workflow includes all plugin configuration
Immutable — changing a blueprint node requires re-running the wizard, which regenerates the script

Visual Indicators

On the workflow canvas, blueprint nodes appear with a circular icon matching their category, distinguishing them from standard star-shaped action nodes. Double-clicking a blueprint node re-opens the wizard for editing.

Script Template System

Each blueprint definition includes a scriptTemplate — a JavaScript code template with {{placeholder}} tokens that are substituted with wizard values.

How Templates Work

The wizard collects values for each field (e.g., url, method, apiKey)
Each {{key}} in the template is replaced with the field's value, rendered according to its renderAs mode:
- string — wrapped in quotes: "https://api.example.com"
- identifier — bare variable name: MY_API_KEY
- expression — raw expression: { key: "value" }
- template — Nunjucks rendered string
The resulting script is stored as preScript on the node

Example: HTTP Request Template

Template:

const result = await httpRequest({
  url: {{url}},
  method: {{method}},
  followRedirects: {{followRedirects}},
  apiKey: {{apiKey}},
  apiKeyHeader: {{apiKeyHeader}},
  body: {{body}},
});
print("HTTP", result.status, {{method}}, {{url}});

With wizard values url="https://api.example.com/v1/data", method="POST", apiKey=MY_API_KEY, the generated script becomes:

const result = await httpRequest({
  url: "https://api.example.com/v1/data",
  method: "POST",
  followRedirects: true,
  apiKey: MY_API_KEY,
  apiKeyHeader: "x-api-key",
  body: { key: "value" },
});
print("HTTP", result.status, "POST", "https://api.example.com/v1/data");

Blueprint Outputs

Each blueprint defines expected output paths so the admin UI can suggest variables for downstream entities:

Output Path	Label	Description
`context.lastResult`	Response / Result	The full return value from the script function
`context.lastResult.status`	Status Code	HTTP status code (HTTP plugins)
`context.lastResult.data`	Response Data	Parsed response body (HTTP plugins)
`context.lastResult.headers`	Response Headers	HTTP response headers
`context.lastResult.linesProcessed`	Lines Processed	Stream line count (HTTP Stream)
`context.lastResult.key`	Storage Key	S3 key (STM Store)
`context.lastResult.url`	Post URL	Mastodon post URL
`context.lastResult.channel`	Channel Name	PubSub channel name
`context.lastResult.subscriberCount`	Subscriber Count	PubSub delivery count

Execution at Runtime

When the consumer encounters an inline blueprint node during workflow traversal:

Detection — the node has a preScript but no entityId, indicating an inline node
Synthetic entity — a temporary entity object is created with ID inline-<ref>, the node's name, and the preScript/postScript
Standard evaluation — the synthetic entity is passed through the same Unified Entity Evaluator pipeline as database-backed entities (arguments → preScript → condition → prompt → postScript)
Entity-resume handling — if the script dispatches via Kinesis (e.g., httpRequest, httpStreamConnect), the __resumeDispatched__ flag prevents in-process child traversal. The children run when the Kinesis message is consumed.
Logging — execution log entries use the synthetic ID and the node's name for traceability

Example Execution Log Entry

{
  "type": "script",
  "action": "executed",
  "entityId": "inline-node-abc123",
  "entityName": "HTTP Request",
  "entityType": "Action",
  "durationMs": 245
}

Plugin Visibility

Not all script modules appear in the Plugin Catalog. Modules set showInPlugins: false to hide from the UI while remaining available for direct script use. Hidden plugins are also excluded from the consumer's database sync — they exist only in code.

Currently hidden plugins include internal utilities like print, evaluateCondition, sleep, and assistantResearch. All plugins listed in the catalog table above have showInPlugins: true.

Database Sync

The consumer synchronizes plugin metadata with the database on startup:

Load definitions — calls getScriptDefinitions() from the shared library to get all script modules
Filter — skips modules with showInPlugins === false
Upsert — creates or updates rows in the Plugin table with name, displayName, category, description, and definitions
Cleanup — deletes rows for modules that were previously visible but are now hidden

This sync ensures the admin UI always reflects the current set of available plugins.

Creating a Blueprint (Seed System)

Blueprints are defined in prisma/seeds/blueprints.ts in the admin project and seeded to the database. Each blueprint seed includes:

interface BlueprintSeed {
  slug: string;               // Unique identifier (e.g., "http-request")
  name: string;               // Display name
  description: string;        // Shown in the catalog
  category: string;           // Grouping (Social, Email, Storage, etc.)
  icon: string;               // Material UI icon name
  entityTypeName: string;     // Always "Action" for current blueprints
  steps: BlueprintStep[];     // Wizard steps with fields
  scriptTemplate: string;     // {{placeholder}} code template
  outputs?: BlueprintOutput[];
  requiredVariables?: BlueprintRequiredVariable[];
}

Blueprints are upserted (created or updated) on each seed run. Deprecated blueprints can be listed in REMOVED_BLUEPRINT_SLUGS for automatic cleanup.

HTTP Plugins Reference — detailed API docs for httpRequest and httpStreamConnect
Scripts Overview — all available V8 script functions
Workflow Canvas — visual workflow editor
Workflow Data Schema — JSON structure including inline nodes

Plugin Catalog​

Available Plugins​

Blueprint Wizard​

Wizard Field Types​

Identifier vs. String Mode​

Validation​

Required Variables​

Inline Blueprint Nodes​

Key Fields​

No Database Entity Required​

Visual Indicators​

Script Template System​

How Templates Work​

Example: HTTP Request Template​

Blueprint Outputs​

Execution at Runtime​

Example Execution Log Entry​

Plugin Visibility​

Database Sync​

Creating a Blueprint (Seed System)​

Related Topics​