Process **REMOTE FILES** or script **BULK TOOL EXECUTIONS** using JavaScript code in a **REMOTE SANDBOX**. If you can see the data in chat, DON'T USE THIS TOOL.
**ONLY** use this when processing **data stored in a remote file** or when scripting bulk tool executions.
BOUNDARY WITH FLOWRA_REMOTE_BASH
- Both tools share one sandbox per session.id and the same /home/user/files files.
- This tool runs JavaScript and keeps variables between calls. Only this tool has run_tool (app tools), invoke_llm, proxy_execute, and upload_local_file.
- FLOWRA_REMOTE_BASH runs one shell command with a fresh shell each call and none of those helpers. Use it for jq, grep, sort, unzip, or listing files.
- Neither tool can call FLOWRA_MULTI_EXECUTE_TOOL or any other FLOWRA_* meta tool.
DO NOT USE
- When the complete response is already inline/in-memory, or you only need quick parsing, summarization, or basic math.
USE IF
- To parse/analyze tool outputs saved to a remote file in the sandbox or to script multi-tool chains there.
- After FLOWRA_MULTI_EXECUTE_TOOL with `syncResponseToWorkbench: true` and the same `session.id`: the snapshot is at **/home/user/files/multi_execute.json** and as **FLOWRA_WORKBENCH_SNAPSHOT**. FLOWRA_REMOTE_BASH sees the same file.
- For bulk or repeated executions of known Flowra tools (e.g., add a label to 100 emails).
- To call APIs via proxy_execute when no Flowra tool exists for that API.
OUTPUTS
- Returns a compact result or, if too long, artifacts for download.
IMPORTANT CODING RULES:
1. Stepwise Execution: Split work into small steps. Save intermediate outputs in variables or temporary storage. Call FLOWRA_JS_REMOTE_WORKBENCH again for the next step. This improves composability and avoids timeouts.
2. Session Persistence: This is a persistent JavaScript execution context: variables, functions, and in-memory state from previous and future code executions are preserved in the sandbox session and available for reuse. Do not import or redeclare the helpers below.
3. Parallelism & Timeout (CRITICAL): There is a hard timeout of 4 minutes. Prioritize PARALLEL execution using Promise.all() with suitable concurrency for bulk operations (e.g., call run_tool or invoke_llm in parallel across items).
3.1 If the data is large, split into smaller batches and call the workbench multiple times to avoid timeouts.
4. Checkpoints: Implement checkpoints (in memory or variables) so that long runs can be resumed from the last completed step.
5. Schema Safety: Never assume the response schema for run_tool if not known already from previous tools. To inspect schema, run a simple request via MULTI_EXECUTE_TOOL or use invoke_llm helper.
6. LLM Helpers: Always use invoke_llm helper for summary, analysis, or field extraction on results. Prefer batching items into smaller groups to stay within token limit.
7. Avoid Meta Loops: Do not use run_tool to call MULTI_EXECUTE_TOOL or other FLOWRA_* meta tools to avoid cycles. Only use it for app tools.
8. Pagination: Use when data spans multiple pages. Continue fetching pages with the returned next_page_token or cursor until none remains. Parallelize fetching pages if the tool supports page_number.
9. No Hardcoding: Never hardcode data in code. Always load it from files or tool responses, iterating to construct intermediate or final inputs/outputs.
10. Code Correctness (CRITICAL): Code must be syntactically and semantically correct and executable (ES5-friendly; avoid ?? or ?. if targeting older runtimes).
GLOBALS (when workbench snapshot loaded)
- FLOWRA_WORKBENCH_SNAPSHOT: full JSON from MULTI_EXECUTE sync, or null if load failed / skipped.
HELPERS (already in sandbox – do not redeclare):
- run_tool(toolSlug, args) -> [result, error]: Execute a known Flowra **app** tool (from DISCOVER_TOOLS). Match the tool's input schema. Returns (data, "") on success; ({}, "error_message") on failure. Check error before using result.
- invoke_llm(query) -> [text, error]: Invoke an LLM for semantic tasks. Pass MAX ~400k characters. Returns (response_text, "") on success; ("", "error_message") on failure.
- proxy_execute(method, endpoint, toolkit, query_params?, body?, headers?) -> [data, error]: Call a connected toolkit API. endpoint is a path on that toolkit's base URL. Credentials stay on the host. Returns (response_data, "") or (null, "error_message").
- upload_local_file(filePath) -> [fileUrl, error]: Upload a file from /home/user/files and return a public download URL.
All helpers return [result, error]. Always check error before using result.
Error-first pattern:
const [res, err] = await run_tool("SOME_TOOL_SLUG", { key: "value" });
if (err) { return { error: err }; }
const data = res.data != null ? res.data : res;
// use data
Parallelize (4-min timeout):
const CONCURRENCY = 10;
const items = [/* ... */];
const results = [];
for (let i = 0; i < items.length; i += CONCURRENCY) {
const batch = items.slice(i, i + CONCURRENCY);
const out = await Promise.all(batch.map(async (item) => {
const [r, e] = await run_tool("TOOL_SLUG", item);
return e ? { status: "failed", error: e } : { status: "ok", data: r };
}));
results.push(...out);
}
return results;
