fix(api): preserve workflow behavior and tighten diagnostics

Author: waleedlatif1

apps/docs/content/docs/cli/index.mdx

@@ -13,7 +13,7 @@ pipelines. See [Output formats](/cli/output) for commands that emit raw content
 or local configuration.
 
 For safe edits, compact run diagnostics, and partial retries, see
-[Agent workflow operations](/cli/agent-workflows).
+[Workflow operations](/cli/workflow-operations).
 
 ## Install
 

apps/docs/content/docs/cli/logs.mdx

@@ -31,8 +31,10 @@ sim logs get <runId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
+| `--include-workflow-state` | No | Include the saved workflow snapshot. Set false to avoid loading and returning block configuration when inspecting a run. Other run fields are unchanged. |
+| `--no-include-workflow-state` | No | Send --include-workflow-state as false. |
 | `--trace` | No | Show expanded trace spans with inputs, outputs, errors, timing, and cost. |
-| `--summary` | No | Show bounded run diagnostics and the explicit application outcome; omit binary content. |
+| `--summary` | No | Show bounded run diagnostics and final output; omit binary content and the workflow snapshot. |
 
 </CommandTable>
 

apps/docs/content/docs/cli/meta.json

@@ -9,7 +9,7 @@
     "output",
     "scripting",
     "workflow-sync",
-    "agent-workflows",
+    "workflow-operations",
     "troubleshooting",
     "usage-data",
     "---Commands---",

apps/docs/content/docs/cli/reference.mdx

@@ -2749,8 +2749,10 @@ sim logs get <runId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
+| `--include-workflow-state` | No | Include the saved workflow snapshot. Set false to avoid loading and returning block configuration when inspecting a run. Other run fields are unchanged. |
+| `--no-include-workflow-state` | No | Send --include-workflow-state as false. |
 | `--trace` | No | Show expanded trace spans with inputs, outputs, errors, timing, and cost. |
-| `--summary` | No | Show bounded run diagnostics and the explicit application outcome; omit binary content. |
+| `--summary` | No | Show bounded run diagnostics and final output; omit binary content and the workflow snapshot. |
 
 </CommandTable>
 
@@ -5847,7 +5849,7 @@ sim tools files download <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | The returned file.id with context copilot, passed unchanged |
+| `fileId` | Yes | The returned file.id whose file.context is "copilot", passed unchanged |
 
 </CommandTable>
 
@@ -6120,7 +6122,7 @@ sim workflows operations apply <workflowId> [options]
 | --- | --- | --- |
 | `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
 | `--no-dry-run` | No | Send --dry-run as false. |
-| `--operations <json\|@file>` | Yes | Edits to apply, in a single batch, keyed by operation_type: [&#123;"operation_type":"add","block_id":"my-fn","params":&#123;"type":"function","name":"My Fn","inputs":&#123;"code":"return &#123;ok:true&#125;"&#125;&#125;&#125;,&#123;"operation_type":"edit","block_id":"&lt;uuid&gt;","params":&#123;"name":"Renamed","connections":&#123;"success":"my-fn"&#125;&#125;&#125;,&#123;"operation_type":"delete","block_id":"&lt;uuid&gt;"&#125;]. Also extract_from_subflow, whose params carry &#123;"subflowId":"&lt;loop-id&gt;"&#125;, and insert_into_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
+| `--operations <json\|@file>` | No | Edits to apply, in a single batch, keyed by operation_type: [&#123;"operation_type":"add","block_id":"my-fn","params":&#123;"type":"function","name":"My Fn","inputs":&#123;"code":"return &#123;ok:true&#125;"&#125;&#125;&#125;,&#123;"operation_type":"edit","block_id":"&lt;uuid&gt;","params":&#123;"name":"Renamed","connections":&#123;"success":"my-fn"&#125;&#125;&#125;,&#123;"operation_type":"delete","block_id":"&lt;uuid&gt;"&#125;]. Also extract_from_subflow, whose params carry &#123;"subflowId":"&lt;loop-id&gt;"&#125;, and insert_into_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
 | `--atomic` | No | Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead. |
 | `--no-atomic` | No | Send --atomic as false. |
 | `--layout <value>` | No | Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied. Accepted values: `targeted`, `none`. |

apps/docs/content/docs/cli/tools.mdx

@@ -88,7 +88,7 @@ Download a direct tool output owned by the current user (OAuth login or personal
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | The returned file.id with context copilot, passed unchanged |
+| `fileId` | Yes | The returned file.id whose file.context is "copilot", passed unchanged |
 
 </CommandTable>
 

…ocs/content/docs/cli/agent-workflows.mdx …content/docs/cli/workflow-operations.mdxapps/docs/content/docs/cli/agent-workflows.mdx renamed to apps/docs/content/docs/cli/workflow-operations.mdx apps/docs/content/docs/cli/agent-workflows.mdx renamed to apps/docs/content/docs/cli/workflow-operations.mdx

@@ -1,5 +1,5 @@
 ---
-title: Agent workflow operations
+title: Workflow operations
 description: Edit bindings safely, inspect compact run evidence, and track partial retries
 ---
 
@@ -18,10 +18,29 @@ sim --output json credentials get "$CREDENTIAL_ID"
 ```
 
 Use the returned tool ID and parameter schema; do not derive IDs from an English
-verb. For example, Slack sending uses `slack_message`. Supply the intended
-credential ID in the tool's documented credential parameter. A workflow can use
-a different credential from a direct tool call even when both are started by the
-same Sim user.
+verb. For example, Slack sending uses `slack_message`. For standalone OAuth
+execution, supply the intended top-level `credentialId`. Slack tools that declare
+`authMethod` and `botToken` also accept `input.authMethod: "bot_token"` with
+`input.botToken`, including an authorized `{{SECRET_NAME}}` reference. Explicit
+bot-token mode ignores `credentialId`; OAuth is the default and ignores an unused
+`botToken`. OAuth-only tools retain their credential requirement.
+
+A workflow can use a different credential from a direct tool call even when both
+are started by the same Sim user. Changing credentials can change the Slack bot's
+identity and which messages it may update.
+
+| Identifier | Where to read it | What it selects |
+| --- | --- | --- |
+| Tool ID | `tools list` and `tools get` | One executable operation and its standalone arguments |
+| Block type | `blocks list`, `blocks get`, and saved workflow state | A workflow block definition and its version |
+| Block operation | The returned block definition | An operation within that block; its ID may differ from the tool ID |
+| Block ID | Saved workflow state or a committed edit response | One particular block in that workflow |
+
+For example, `serper_search` is a tool ID, while `serper` is its integration
+type. Keep the exact type stored in an existing workflow; a catalog lookup of an
+unversioned name can resolve to a newer definition. Use that version's returned
+fields and operation IDs when editing, and the tool's returned parameter schema
+when executing directly.
 
 `credentials get` reports the credential type/provider, stored identity metadata,
 and recorded scopes with their source. `verifiedLive: false` means inspection
@@ -90,6 +109,12 @@ empty `mintedBlockIds`. Commit the edit and use that response's `mintedBlockIds`
 preview IDs are not reserved. Inspect the saved workflow to confirm its enabled
 blocks and connections before executing.
 
+For enablement-only changes, send `setBlockEnabled` through the existing workflow
+operations endpoint; no dummy graph edit is needed. Use `atomic: true` when any
+declined edit or dropped input should prevent the batch from saving. Inspect
+`applied`, `skipped`, and `inputValidationErrors`, then read the saved state before
+deploying. Validation does not execute blocks or suppress external writes.
+
 ## Discover workflows across workspaces
 
 Use `workspaces list`, then `workflows list --workspace <id>` for each relevant
@@ -125,12 +150,13 @@ sim --output json workflows runs get "$RUN_ID" --workflow "$WORKFLOW_ID" \
   --select-output "Verify delivery.result"
 ```
 
-`--summary` reports execution status, recorded failures (including handled
-errors), compact failing inputs/outputs, observed block statuses, and file
+`--summary` reports execution status, existing final output, recorded failures
+(including handled errors), compact failing inputs/outputs, observed block statuses, and file
 metadata. It caps trace traversal and field/text output and reports `truncated`
-when it omits detail. Binary fields and data URLs are omitted. This is a local
-projection of the authorized log response; it reduces terminal/context output,
-not the size of the server's log read. Use `logs get --trace` or explicit output
+when it omits detail. Binary fields and data URLs are omitted. The CLI asks the server to omit the saved workflow snapshot, then
+projects the remaining authorized log response locally. HTTP and MCP callers can
+set `includeWorkflowState=false`; ordinary CLI reads can use
+`--no-include-workflow-state`. Trace materialization is unchanged. Use `logs get --trace` or explicit output
 selectors when more detail is needed.
 
 Selectors accept an unambiguous block name or ID followed by an optional output
@@ -140,26 +166,15 @@ Ambiguous names are rejected with candidate IDs. Missing output paths can be
 omitted; that does not establish that a block ran successfully.
 
 A completed run can have sent a failure explanation rather than delivered a
-document. Have the workflow deliberately emit an `applicationOutcome` field in
-its final output, for example:
-
-```json
-{
-  "applicationOutcome": {
-    "status": "verification_blocked",
-    "threadId": "<provider-thread-id>",
-    "fileIds": []
-  }
-}
-```
+document. Inspect the workflow's existing `finalOutput` and recorded tool failures;
+`--summary` preserves the output's shape within its size limits. Execution status
+describes the run, not the quality of its result or an external delivery guarantee.
+Trace entries describe recorded work, and expired trace data may leave no
+block-level evidence.
 
-Choose application statuses that describe the workflow's result, such as
-`delivered`, `clarification_requested`, or `verification_blocked`. The summary
-copies this field at the top level, or inside a Function block's `result` or a
-Response block's `data` wrapper; it does not infer it from a successful execution or a Slack
-message. A null outcome means the workflow did not report one. Trace entries
-describe observed work, and cannot prove unrecorded downstream effects or content
-quality. Expired trace data may leave no block-level evidence.
+The log's existing `cost` includes a reconciled total and itemized `fixed`, `model`,
+and `tool` charges when a ledger is available. Use `logs list --level error
+--include-handled-errors` to find recorded failures that a workflow recovered from.
 
 ## Track long manual runs
 
@@ -177,6 +192,14 @@ blocks are candidates, not a promise of execution order: conditions, disabled
 blocks, loops, and runtime failures still affect the path. A later run uses the
 draft saved at that time; preview does not lock a snapshot.
 
+An error connection is an alternative execution path. A consumer reached through
+an error bypass can run without output from the successful path's parser or
+transform. If that output is required, keep the consumer on the path that produces
+it, or explicitly handle its absence. A disabled block stops its branch; it is not
+a pass-through mock. Replaying from a later block can reuse recorded ancestor
+outputs from the selected source run, but cannot manufacture outputs that run
+never produced.
+
 ```sh
 sim workflows run "$WORKFLOW_ID" --from-block "$BLOCK_ID" \
   --source-run "$SOURCE_RUN_ID" --follow
@@ -221,9 +244,10 @@ does not disable blocks or edit the saved graph. It is unavailable with `--async
 If a condition skips the target, the remaining path can complete normally.
 If the run pauses, a later explicit resume does not inherit the stop-after limit.
 
-Deployed execution uses the deployment snapshot. A workflow with only one
-runnable Schedule trigger can run directly. When multiple entry points are
-ambiguous, select the intended deployed trigger with the API's
+Deployed execution uses the deployment snapshot and retains the existing API
+trigger priority when an API-compatible entry is available. A workflow with only
+one runnable Schedule trigger can also run directly. When no API-compatible entry
+exists and multiple triggers remain, select the intended deployed trigger with the API's
 `run: { "source": "deployment", "entry": { "type": "trigger", "blockId": "<block-id>" } }`.
 Manual trigger execution remains a separate choice that uses the saved draft.
 

apps/docs/content/docs/cli/workflows.mdx

@@ -64,7 +64,7 @@ Apply Workflow Operations (OAuth login or personal API key required)
 | --- | --- | --- |
 | `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
 | `--no-dry-run` | No | Send --dry-run as false. |
-| `--operations <json\|@file>` | Yes | Edits to apply, in a single batch, keyed by operation_type: [&#123;"operation_type":"add","block_id":"my-fn","params":&#123;"type":"function","name":"My Fn","inputs":&#123;"code":"return &#123;ok:true&#125;"&#125;&#125;&#125;,&#123;"operation_type":"edit","block_id":"&lt;uuid&gt;","params":&#123;"name":"Renamed","connections":&#123;"success":"my-fn"&#125;&#125;&#125;,&#123;"operation_type":"delete","block_id":"&lt;uuid&gt;"&#125;]. Also extract_from_subflow, whose params carry &#123;"subflowId":"&lt;loop-id&gt;"&#125;, and insert_into_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
+| `--operations <json\|@file>` | No | Edits to apply, in a single batch, keyed by operation_type: [&#123;"operation_type":"add","block_id":"my-fn","params":&#123;"type":"function","name":"My Fn","inputs":&#123;"code":"return &#123;ok:true&#125;"&#125;&#125;&#125;,&#123;"operation_type":"edit","block_id":"&lt;uuid&gt;","params":&#123;"name":"Renamed","connections":&#123;"success":"my-fn"&#125;&#125;&#125;,&#123;"operation_type":"delete","block_id":"&lt;uuid&gt;"&#125;]. Also extract_from_subflow, whose params carry &#123;"subflowId":"&lt;loop-id&gt;"&#125;, and insert_into_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
 | `--atomic` | No | Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead. |
 | `--no-atomic` | No | Send --atomic as false. |
 | `--layout <value>` | No | Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied. Accepted values: `targeted`, `none`. |

apps/docs/content/docs/mcp/index.mdx

@@ -145,7 +145,7 @@ named MCP tool for every operation. Use `search_operations` and
 | Edit an existing workflow | [Workflow commands](/cli/workflows) | `getWorkflowState` and `replaceWorkflowState` | Invokes the deployed workflow; does not expose the workspace editing API |
 | Deploy a workflow | [Workflow commands](/cli/workflows) | `deployWorkflow` | Configure the deployment in Sim or through CLI/API/hosted MCP |
 | Invoke a workflow | [Workflow commands](/cli/workflows) | `executeWorkflow`; async execution is deployment-only, while manual runs are synchronous or streamed through CLI/API | The selected workflows appear as their own tools |
-| Preview a partial retry | [Agent workflow guide](/cli/agent-workflows) | `previewWorkflowRunFromBlock` reports candidate reruns and cached-output availability without executing | Not part of the deployed workflow tool interface |
+| Preview a partial retry | [Workflow operations guide](/cli/workflow-operations) | `previewWorkflowRunFromBlock` reports candidate reruns and cached-output availability without executing | Not part of the deployed workflow tool interface |
 | Inspect runs and outputs | [Workflow commands](/cli/workflows) | `listWorkflowRuns`, `getWorkflowRun`, and other discovered run operations | Returns the invoked workflow's result |
 | Search workspace knowledge | [Knowledge commands](/cli/knowledge) | `searchKnowledge` | Only if the workflow performs that search |
 | Search live organization sources | Use the dedicated [Search MCP](/search/mcp) connection | Separate endpoint with `search` and `read_document` tools | Only if the workflow performs that search |

apps/docs/content/docs/workflows/blocks/function.mdx

@@ -157,6 +157,13 @@ JavaScript without imports runs in a fast local sandbox. JavaScript with `import
 | **HTTP requests** | `fetch()` built in | `requests` or `httpx` | `curl` or an installed CLI |
 | **Best for** | quick transforms and JSON | scripts, data science, charts, complex math | CLI workflows and system utilities |
 
+The fast local JavaScript runtime provides standard ECMAScript values, `fetch`,
+`console`, and Sim helpers. It does not provide Node/browser globals such as
+`process`, `Buffer`, `require`, `crypto`, `TextDecoder`, `atob`, or `setTimeout`.
+Code that needs Node APIs or timers must use the remote JavaScript runtime with
+an import, for example `import { setTimeout as delay } from 'node:timers/promises'`.
+Use `{{SECRET_NAME}}` for selected secrets in either runtime.
+
 <Callout type="info">
 Python and Shell require a remote sandbox. They are enabled by default on sim.ai;
 on a self-hosted instance, build and configure the provider's dedicated

apps/docs/openapi-v2-logs.json

@@ -383,6 +383,16 @@
               "pattern": "^[A-Za-z0-9._:-]+$",
               "description": "Unique workflow run identifier."
             }
+          },
+          {
+            "name": "includeWorkflowState",
+            "in": "query",
+            "required": false,
+            "description": "Include the saved workflow snapshot. Set false to avoid loading and returning block configuration when inspecting a run. Other run fields are unchanged.",
+            "schema": {
+              "description": "Include the saved workflow snapshot. Set false to avoid loading and returning block configuration when inspecting a run. Other run fields are unchanged.",
+              "type": "boolean"
+            }
           }
         ],
         "responses": {
@@ -1602,7 +1612,7 @@
                 "type": "null"
               }
             ],
-            "description": "Workflow graph captured for the run, or null if unavailable. Sensitive values are redacted to null; environment-variable references may be preserved."
+            "description": "Credential-redacted workflow snapshot, or null when unavailable or includeWorkflowState=false."
           },
           "traceSpans": {
             "type": "array",