Polyglot tasks

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

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