improvement(executor): redesign executor + add start block (#1790)

* fix(billing): should allow restoring subscription (#1728)

* fix(already-cancelled-sub): UI should allow restoring subscription

* restore functionality fixed

* fix

* improvement(start): revert to start block

* make it work with start block

* fix start block persistence

* cleanup triggers

* debounce status checks

* update docs

* improvement(start): revert to start block

* make it work with start block

* fix start block persistence

* cleanup triggers

* debounce status checks

* update docs

* SSE v0.1

* v0.2

* v0.3

* v0.4

* v0.5

* v0.6

* broken checkpoint

* Executor progress - everything preliminarily tested except while loops and triggers

* Executor fixes

* Fix var typing

* Implement while loop execution

* Loop and parallel result agg

* Refactor v1 - loops work

* Fix var resolution in for each loop

* Fix while loop condition and variable resolution

* Fix loop iteration counts

* Fix loop badges

* Clean logs

* Fix variable references from start block

* Fix condition block

* Fix conditional convergence

* Dont execute orphaned nodse

* Code cleanup 1 and error surfacing

* compile time try catch

* Some fixes

* Fix error throwing

* Sentinels v1

* Fix multiple start and end nodes in loop

* Edge restoration

* Fix reachable nodes execution

* Parallel subflows

* Fix loop/parallel sentinel convergence

* Loops and parallels orchestrator

* Split executor

* Variable resolution split

* Dag phase

* Refactor

* Refactor

* Refactor 3

* Lint + refactor

* Lint + cleanup + refactor

* Readability

* Initial logs

* Fix trace spans

* Console pills for iters

* Add input/output pills

* Checkpoint

* remove unused code

* THIS IS THE COMMIT THAT CAN BREAK A LOT OF THINGS

* ANOTHER BIG REFACTOR

* Lint + fix tests

* Fix webhook

* Remove comment

* Merge stash

* Fix triggers?

* Stuff

* Fix error port

* Lint

* Consolidate state

* Clean up some var resolution

* Remove some var resolution logs

* Fix chat

* Fix chat triggers

* Fix chat trigger fully

* Snapshot refactor

* Fix mcp and custom tools

* Lint

* Fix parallel default count and trace span overlay

* Agent purple

* Fix test

* Fix test

---------

Co-authored-by: Waleed <[email protected]>
Co-authored-by: Vikhyath Mondreti <[email protected]>
Co-authored-by: Vikhyath Mondreti <[email protected]>

Author: 3 people

apps/docs/content/docs/en/triggers/index.mdx

@@ -7,46 +7,35 @@ import { Card, Cards } from 'fumadocs-ui/components/card'
 
 ## Core Triggers
 
-Pick one trigger per workflow to define how it starts:
+Use the Start block for everything originating from the editor, deploy-to-API, or deploy-to-chat experiences. Other triggers remain available for event-driven workflows:
 
 <Cards>
-  <Card title="API" href="/triggers/api">
-    HTTP endpoint that maps JSON bodies into workflow inputs
+  <Card title="Start" href="/triggers/start">
+    Unified entry point that supports editor runs, API deployments and chat deployments
   </Card>
-  <Card title="Chat" href="/triggers/chat">
-    Deployed chat interface with streaming responses
-  </Card>
-  <Card title="Input Form" href="/triggers/input-form">
-    Typed manual input used in editor runs and child workflows
-  </Card>
-  <Card title="Manual" href="/triggers/manual">
-    On-demand runs with no additional data
+  <Card title="Webhook" href="/triggers/webhook">
+    Receive external webhook payloads
   </Card>
   <Card title="Schedule" href="/triggers/schedule">
     Cron or interval based execution
   </Card>
-  <Card title="Webhook" href="/triggers/webhook">
-    Receive external webhook payloads
-  </Card>
 </Cards>
 
 ## Quick Comparison
 
 | Trigger | Start condition |
 |---------|-----------------|
-| **API** | Authenticated HTTP POST |
-| **Chat** | Chat deployment message |
-| **Input Form** | On manual submit in editor or parent workflow |
-| **Manual** | Run button in editor |
+| **Start** | Editor runs, deploy-to-API requests, or chat messages |
 | **Schedule** | Timer managed in schedule modal |
 | **Webhook** | On inbound HTTP request |
 
+> The Start block always exposes `input`, `conversationId`, and `files` fields. Add custom fields to the input format for additional structured data.
+
 ## Using Triggers
 
-1. Drop the trigger block in the start slot.
+1. Drop the Start block in the start slot (or an alternate trigger like Webhook/Schedule).
 2. Configure any required schema or auth.
 3. Connect the block to the rest of the workflow.
 
 > Deployments power every trigger. Update the workflow, redeploy, and all trigger entry points pick up the new snapshot. Learn more in [Execution → Deployment Snapshots](/execution).
 
-Legacy Starter blocks remain for existing flows but no longer appear in new builds.

apps/docs/content/docs/en/triggers/meta.json

@@ -1,3 +1,3 @@
 {
-  "pages": ["index", "api", "chat", "input-form", "manual", "schedule", "starter", "webhook"]
+  "pages": ["index", "start", "schedule", "webhook", "starter"]
 }

apps/docs/content/docs/en/triggers/start.mdx

@@ -0,0 +1,90 @@
+---
+title: Start
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Image } from '@/components/ui/image'
+
+The Start block is the default trigger for workflows built in Sim. It collects structured inputs and fans out to the rest of your graph for editor tests, API deployments, and chat experiences.
+
+<div className="flex justify-center">
+  <Image
+    src="/static/start.png"
+    alt="Start block with Input Format fields"
+    width={360}
+    height={380}
+    className="my-6"
+  />
+</div>
+
+<Callout type="info">
+The Start block sits in the start slot when you create a workflow. Keep it there when you want the same entry point to serve editor runs, deploy-to-API requests, and chat sessions. Swap it with Webhook or Schedule triggers when you only need event-driven execution.
+</Callout>
+
+## Fields exposed by Start
+
+The Start block emits different data depending on the execution surface:
+
+- **Input Format fields** — Every field you add becomes available as `<start.fieldName>`. For example, a `customerId` field shows up as `<start.customerId>` in downstream blocks and templates.
+- **Chat-only fields** — When the workflow runs from the chat side panel or a deployed chat experience, Sim also provides `<start.input>` (latest user message), `<start.conversationId>` (active session id), and `<start.files>` (chat attachments).
+
+Keep Input Format fields scoped to the names you expect to reference later—those values are the only structured fields shared across editor, API, and chat runs.
+
+## Configure the Input Format
+
+Use the Input Format sub-block to define the schema that applies across execution modes:
+
+1. Add a field for each value you want to collect.
+2. Choose a type (`string`, `number`, `boolean`, `object`, `array`, or `files`). File fields accept uploads from chat and API callers.
+3. Provide default values when you want the manual run modal to populate test data automatically. These defaults are ignored for deployed executions.
+4. Reorder fields to control how they appear in the editor form.
+
+Reference structured values downstream with expressions such as `<start.customerId>` depending on the block you connect.
+
+## How it behaves per entry point
+
+<Tabs items={['Editor run', 'Deploy to API', 'Deploy to chat']}>
+  <Tab>
+    <div className="space-y-3">
+      <p>
+        When you click <strong>Run</strong> in the editor, the Start block renders the Input Format as a form. Default values make it easy to retest without retyping data. Submitting the form triggers the workflow immediately and the values become available on <code>&lt;start.fieldName&gt;</code> (for example <code>&lt;start.sampleField&gt;</code>).
+      </p>
+      <p>
+        File fields in the form upload directly into the corresponding `<start.fieldName>`; use those values to feed downstream tools or storage steps.
+      </p>
+    </div>
+  </Tab>
+  <Tab>
+    <div className="space-y-3">
+      <p>
+        Deploying to API turns the Input Format into a JSON contract for clients. Each field becomes part of the request body, and Sim coerces primitive types on ingestion. File fields expect objects that reference uploaded files; use the execution file upload endpoint before invoking the workflow.
+      </p>
+      <p>
+        API callers can include additional optional properties. They are preserved inside `<start.fieldName>` outputs so you can experiment without redeploying immediately.
+      </p>
+    </div>
+  </Tab>
+  <Tab>
+    <div className="space-y-3">
+      <p>
+        In chat deployments the Start block binds to the active conversation. The latest message fills <code>&lt;start.input&gt;</code>, the session identifier is available at <code>&lt;start.conversationId&gt;</code>, and user attachments appear on <code>&lt;start.files&gt;</code>, alongside any Input Format fields scoped as <code>&lt;start.fieldName&gt;</code>.
+      </p>
+      <p>
+        If you launch chat with additional structured context (for example from an embed), it merges into the corresponding `<start.fieldName>` outputs, keeping downstream blocks consistent with API and manual runs.
+      </p>
+    </div>
+  </Tab>
+</Tabs>
+
+## Referencing Start data downstream
+
+- Connect `<start.fieldName>` directly into agents, tools, or functions that expect structured payloads.
+- Use templating syntax like `<start.sampleField>` or `<start.files[0].url>` (chat only) in prompt fields.
+- Keep `<start.conversationId>` handy when you need to group outputs, update conversation history, or call back into the chat API.
+
+## Best practices
+
+- Treat the Start block as the single entry point when you want to support both API and chat callers.
+- Prefer named Input Format fields over parsing raw JSON in downstream nodes; type coercion happens automatically.
+- Add validation or routing immediately after Start if certain fields are required for your workflow to succeed.