Polyglot tasks

Keep the script, gain the runtime. A working Python, .NET, or shell step becomes a queued, retried, traced unit of work by declaring it with defineTask — the script itself does not change, and nothing about your platform has to stop being TypeScript for one step that is not.

A polyglot task runs non-TypeScript work — a Python script, a .NET program, a shell or PowerShell script, or any executable — as a managed subprocess spawned by the worker runtime. NetScript hands the task its input as command-line arguments and environment variables, captures every line of stdout/stderr, parses a final JSON line into a structured result, and normalizes the exit code into a TaskResult. It is the escape hatch for the moments your platform is otherwise all-TypeScript: an ML model in Python, a legacy .NET DLL, a system pwsh script. alpha

The typical story is an import pipeline with one step that already exists in another language: a legacy-data transform owned by a Python script, say, sitting in the middle of an otherwise-TypeScript flow. Rewriting it buys nothing; running it ad hoc loses the queue, retry, and trace behavior every other step has. Declaring it as a task resolves that tension — the ERP Sync tutorial walks exactly this step, and trace context is injected into the subprocess environment so the Python span stitches into the same trace as the TypeScript steps around it.

What it is

A job runs in-process TypeScript on a worker; a task runs a subprocess in another runtime. Tasks share the worker plugin's queue, retry, and telemetry machinery with background jobs — the difference is purely the execution surface. The MultiRuntimeTaskExecutor keeps a map of runtime adapters (one per TaskType) and dispatches a TaskDefinition to the adapter that supports its type. Each adapter builds an argv for its runtime (e.g. python3 -u script.py …, pwsh -File script.ps1 …) and runs it through a Dax-backed process runner that streams output and times the process out. This page covers that subprocess seam; for in-process TS handlers, runtime modes, and the queue lifecycle, start at background jobs.

Learn → / Do →

Minimal example

A task is authored with the defineTask typestate builder, then run through the default multi-runtime executor. The builder's default runtime is 'deno'; call .runtime(type) to target another language. Input reaches the script as argv (.args(...)) and environment variables (.env({...})); the script returns a result by writing a single JSON object as the last line of stdout.

// workers/tasks/score-batch.ts
import { defineTask } from '@netscript/plugin-workers-core/builders';
import { createDefaultTaskExecutor } from '@netscript/plugin-workers-core/executor';

// Build a task definition: python runtime, script entrypoint, explicit inputs.
const scoreBatch = defineTask('score-batch')
  .runtime('python')
  .entrypoint('./scripts/score.py')
  .env({ MODEL_PATH: './models/scorer.pkl' })
  .args('--threshold', '0.8')
  .timeout(120_000) // ms; defaults to 300_000
  .build();

// The executor resolves the python adapter and spawns: python3 -u ./scripts/score.py --threshold 0.8
const executor = createDefaultTaskExecutor();
const result = await executor.execute(scoreBatch, {
  onStdout: (line) => console.log('[score]', line),
});

if (result.success) {
  // result.result is the parsed JSON object from the LAST stdout line, or null.
  console.log('scored', result.result);
} else {
  console.error('task failed', result.exitCode, result.error);
}

# scripts/score.py
import json, os, sys

# Input arrives as argv + env (NOT stdin).
threshold = float(sys.argv[sys.argv.index('--threshold') + 1])
model_path = os.environ['MODEL_PATH']

# ... do the work ...
scored = {'kept': 42, 'dropped': 3, 'threshold': threshold}

# Any prior prints become captured logs. The result is the LAST line of stdout,
# and must be a single JSON object (not an array) to populate result.result.
print('scoring complete', file=sys.stderr)
print(json.dumps(scored))

Key types first — TaskResult

Every task — whatever its runtime — resolves to one TaskResult. This is the shape your calling code reads; check it before writing per-runtime branches.

TaskDefinition & runtimes

defineTask(id) returns a typestate builder; .build() is only callable once an .entrypoint(path) (subprocess) or .handler(fn) (in-process) is set. The resulting TaskDefinition carries the runtime type, entrypoint, args, env, timeout, and permissions. The seven supported runtimes (TaskType) and how each is launched:

The per-task permission set passed to .permissions(...) mirrors the Deno permission model. It is enforced only for the deno runtime — those keys are translated into --allow-* flags on the deno run command line. For python, shell, and the other external runtimes there is no Deno sandbox; the subprocess inherits the OS-level access of the worker process.

Production notes

Reference →

The full generated API — defineTask, MultiRuntimeTaskExecutor, createDefaultTaskExecutor, every runtime adapter, and the executor option types — lives in the workers reference.

workers