Script Steps via script.execute (SES)¶
Run JavaScript, Python, or Bash from workflows through the Script Execution Service (SES)
as a normal capability provider — type: service_call + capability_name: script.execute.
Internal reference: internal/SCRIPT_STEPS_GUIDE.md. Step type overview: Step Types.
Overview¶
runtime |
SES engine |
|---|---|
javascript |
QuickJS sandbox |
python |
CPython subprocess + AST allowlist (phase-1; see Security) |
bash |
/bin/bash subshell |
Orchestrator resolves script.execute via the capability registry, POSTs to SES /v1/execute
(Bearer SES_SERVICE_TOKEN / ORCH_SES_TOKEN), and unwraps {ok, result} as the step output.
Unified contract¶
Every script has access to:
| Variable | Description |
|---|---|
input |
Step input from payload_from (previous step / initial / step id) |
context |
Workflow context map injected by the orchestrator (string values) |
result |
Must be assigned — becomes step output |
// JavaScript
result = input.toUpperCase();
# Python
result = input.upper()
# Bash
result=$(echo "$input" | tr '[:lower:]' '[:upper:]')
Using context¶
The orchestrator sends the current run context as string key/value pairs. Typical keys include
workflow_id, request_id, trigger.request_id, and DSAV fields such as dsav.domain after a
topic publish. Prefer bracket access for dotted keys.
JavaScript
const domain = String(context["dsav.domain"] || "Unknown").trim() || "Unknown";
const rid = String(context["trigger.request_id"] || context.request_id || "unknown");
result = JSON.stringify({ domain: domain, request_id: rid, body: input });
Python
domain = (context.get("dsav.domain") or "Unknown").strip() or "Unknown"
rid = context.get("trigger.request_id") or context.get("request_id") or "unknown"
result = f"{domain}/{rid}: {input}"
Live workflow that builds an S3 key from DSAV context:
flows/workflows/dsav_message_archive.yaml
(build_put_payload).
Examples¶
JavaScript¶
steps:
- id: parse_date
type: service_call
capability_name: script.execute
capability_version: "^1.0"
path: /v1/execute
payload_from: initial
runtime: javascript
code: |
result = new Date().toISOString();
timeout_seconds: 30
JavaScript with context (DSAV-style)¶
steps:
- id: build_put_payload
type: service_call
capability_name: script.execute
capability_version: "^1.0"
path: /v1/execute
payload_from: initial
runtime: javascript
timeout_ms: 10000
code: |
const domain = String(context["dsav.domain"] || "Unknown").trim() || "Unknown";
const rid = String(context["trigger.request_id"] || "unknown").trim() || "unknown";
const body = typeof input === "string" ? input : JSON.stringify(input);
result = JSON.stringify({
bucket: "object-demo",
key: domain + "/" + rid + ".json",
body: body,
content_type: "application/json"
});
timeout_seconds: 30
Python¶
steps:
- id: filter_records
type: service_call
capability_name: script.execute
capability_version: "^1.0"
path: /v1/execute
payload_from: previous
runtime: python
timeout_ms: 15000
code: |
import json
data = json.loads(input)
result = json.dumps([r for r in data['items'] if r['status'] == 'active'])
timeout_seconds: 30
Python with context¶
steps:
- id: tag_with_run
type: service_call
capability_name: script.execute
capability_version: "^1.0"
path: /v1/execute
payload_from: previous
runtime: python
code: |
workflow_id = context.get("workflow_id") or "unknown"
result = f"[{workflow_id}] {input}"
timeout_seconds: 30
Bash¶
steps:
- id: count_lines
type: service_call
capability_name: script.execute
capability_version: "^1.0"
path: /v1/execute
payload_from: previous
runtime: bash
code: |
result=$(printf '%s' "$input" | wc -l | tr -d ' ')
timeout_seconds: 30
Designer Form¶
SES registers script.execute with designer variants (JavaScript / Python / Bash). Each variant
is a service_call form: capability_name, path, runtime, code (block), payload_from, timeouts.
Operations¶
| Env (orchestrator) | Purpose |
|---|---|
SES_SERVICE_TOKEN / ORCH_SES_TOKEN |
Bearer token for SES /v1/execute |
| Capability registry | Must list SES with script.execute |
SES service: enable runtimes (SES_PYTHON_ENABLED, SES_JAVASCRIPT_ENABLED, SES_BASH_ENABLED)
and set SES_SERVICE_TOKEN to match the orchestrator.
Security & residual risks¶
| Runtime | Isolation model |
|---|---|
javascript |
QuickJS sandbox (strongest of the three) |
python |
AST import/builtin allowlist + hardened subprocess (phase-1) |
bash |
Regex denylist + subshell (high risk; default off) |
Python phase-1 blocks the old regex bypasses (from os import …, pathlib, getattr, …) and applies
Linux rlimits where available. It is not equivalent to QuickJS:
- Same container/UID as SES — not a kernel sandbox
- Static AST policy can miss novel CPython escapes
- Suitable for trusted workflow authors (Bearer-gated SES), not untrusted multi-tenant script input
- Prefer JS or a capability provider when stronger isolation is required
Details: engine/services/script-execution-service/README.md (Security).
Common failures¶
| Symptom | Likely cause |
|---|---|
| capability not found | SES not registered / registry down |
| Missing Bearer token | SES_SERVICE_TOKEN unset on orchestrator |
script.execute … failed (…) |
SES returned ok: false (syntax, sanitizer, timeout) |
| IndentationError in Python | Check code: \| is correctly dedented |
First-class type: javascript|python|bash is not supported; use service_call only.
Need C#?¶
SES does not execute inline C#. Wrap your .NET logic as a capability provider and call it
with service_call — see C# Custom Process in a Workflow
(starter code: Add a Capability Provider).