Skip to content

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).