Background jobs

One typed handler file is the whole job. Registration, dispatch, retry, execution tracking, scheduling, tracing, and the HTTP trigger API all come from the worker runtime — so shipping a working background job (whether you write it or an AI agent does) means authoring a single defineJobHandler module, not first assembling a queue, a worker pool, and an inspection UI around it.

A NetScript background job is a durable, KV-backed TypeScript handler that runs in its own thread-isolated worker, separate from your request-serving services. You author a job as one defineJobHandler(...) callable, give it an id, and the runtime takes care of registration, dispatch, retry, execution tracking, scheduling, and an HTTP API to enqueue and inspect runs. It is the unit you reach for whenever work should happen after a request returns — charging a payment, sending a welcome email, processing an upload — without blocking the caller.

The story: a screenshot becomes a diagnosis

The clearest picture of what this contract buys comes from a production incident-diagnosis assistant built on NetScript for a legacy ERP estate. A support engineer pastes an alert-email screenshot into a chat channel; a background job runs a vision model over the image and extracts the structured fields (program, error number, table, timestamp) that downstream tooling needs to trace the failure.

Two properties of the job contract shaped that worker into its correct form:

• The payload is queue-borne, so it stays small. The first version enqueued the raw image bytes and hit Deno KV's 64 KB enqueue limit. The fix — carry only a small reference through the queue and fetch the bytes back over a typed service client inside the handler — is exactly the shape the contract steers you toward: the queue moves references to work, not blobs.
• Workers stay compute-only. The app's channel database holds an exclusive OS file lock, so a second process opening it crashes outright. Because a job handler receives a ctx and returns a JobResult — rather than a database connection — writing results back through the owning service's typed client was the natural default, not a discipline the team had to invent. The single writer keeps owning its database; the worker never touches it.

The same run is traced end to end: dispatch, execution, progress events, and the subprocess hop (if any) land in the Aspire dashboard without handler-side wiring. The rest of this page is the mechanism behind that story.

What it is

A job is plain TypeScript that runs in the worker process, not the request process. The headline surface — defineJobHandler, createSuccessResult, and createFailureResult from @netscript/plugin-workers-core — lets you write a typed handler over a ctx, do the work, and return a structured JobResult. Job dispatch and execution are instrumented with real OpenTelemetry spans that show up in the Aspire dashboard automatically, so a queued run is observable end to end without wiring. The runner mode (how the handler is isolated) is a user-tunable — see the runtime-mode table below — and the same queue and scheduler also drive polyglot tasks when the work is owned by another runtime. The why-behind-the-choreography lives in Durability model.

Learn → / Do →

Minimal example

Add the workers plugin to a published workspace with the public package install flow:

netscript plugin install @netscript/plugin-workers

For local-source contributor work inside this monorepo, use the maintainer binary when you need first-party samples:

deno run -A packages/cli/bin/netscript-dev.ts plugin install worker --name workers --samples

That local path lands real, compiling modules you can read and trigger immediately — including plugins/workers/jobs/health-check.ts (a job handler) and plugins/workers/tasks/validate-payload.ts (a polyglot task). The plugin's API service comes up on port 8091.

A job handler is an async callable over a ctx object that returns a JobResult. Parse the payload with a Zod schema, do the work, and return createSuccessResult(...) or createFailureResult(...). The job's identity is attached with Object.assign(handler, { id }).

// plugins/workers/jobs/process-payment.ts
import {
  createFailureResult,
  createSuccessResult,
  defineJobHandler,
} from '@netscript/plugin-workers-core';
import { z } from 'zod';

// Payload contract — parse ctx.payload before doing any work.
const ProcessPaymentPayloadSchema = z.object({
  orderId: z.string().min(1),
  amountCents: z.number().int().positive(),
});

const handler = defineJobHandler(async (ctx) => {
  const { orderId, amountCents } = ProcessPaymentPayloadSchema.parse(ctx.payload ?? {});

  // Optional progress callback — the runtime wires reportProgress on real runs.
  ctx.reportProgress?.(10, 'charging customer');

  const charge = await chargeCustomer(orderId, amountCents);
  if (!charge.ok) {
    // A failure result is recorded and feeds the retry policy.
    return createFailureResult(`charge declined: ${charge.reason}`);
  }

  ctx.reportProgress?.(100, 'charged');
  // The success payload (data) is persisted on the execution record.
  return createSuccessResult({ orderId, chargeId: charge.id, amountCents });
});

// The id is how the runtime registers, lists, and triggers the job.
export default Object.assign(handler, { id: 'process-payment' });

Once the workers API is up (Aspire first — see Production notes), enqueue a run by id:

# Enqueue through the workers API (port 8091), without hand-writing HTTP.
ns-workers trigger process-payment \
  --payload='{"orderId":"o_42","amountCents":4999}'

# Watch it land in the KV-backed execution history.
ns-workers executions --limit=10 --json

Key types first — JobHandlerContext & JobResult

A handler is (ctx: JobHandlerContext<TPayload>) => JobResult<TResult> | Promise<…>. These two shapes are the contract you write against; read them before the option tables.

Worker runtime modes (WORKER_RUNTIMES)

How a handler is isolated from the API process is a tunable: WORKER_RUNTIMES enumerates the three runner modes the worker runtime supports. The scaffold default is web-worker, where each worker is its own V8 isolate sized by the WORKERS_CONCURRENCY env var. Pick the mode that matches your isolation, memory, and parallelism needs.

Enqueue from a trigger

The HTTP …/trigger endpoint is one way in; the other is declaratively, from a trigger handler, which returns an enqueueJob(...) action. enqueueJob(job, options) comes from @netscript/plugin-triggers-core and binds an imported job definition to a payload, so an inbound webhook or a scheduled trigger drops work onto this same runtime.

// plugins/triggers/triggers/payment-webhook.ts
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core';
// Import the job definition you want to dispatch (its default export carries the id).
import processPayment from '../../workers/jobs/process-payment.ts';

const handler = defineWebhook(
  // The handler returns trigger actions; enqueueJob is the most common one.
  (event) => [
    enqueueJob(processPayment, {
      payload: { orderId: event.payload.orderId, amountCents: event.payload.amountCents },
      idempotencyKey: event.payload.orderId, // optional: collapse duplicate deliveries
    }),
  ],
  { id: 'payment-webhook', path: '/webhooks/payment', verifier: 'hmac-sha256', secretEnv: 'WEBHOOK_SECRET' },
);

export default handler;

Trigger a job from a typed client

The ns-workers trigger command above calls the same OpenAPI route. Because the workers API is a plugin service, the same trigger is reachable with a generated typed client over the RPC route /api/rpc/* — no OpenAPI-only fallback and no transport 404. A first-party plugin API mounts its router under a named segment, so the client takes a routerName alongside serviceName; Aspire injects the URL under services__workers-api__http__0.

// Reach the workers plugin API with a generated typed client.
import { createServiceClient } from '@netscript/sdk/client';
import { workersContract } from '@netscript/plugin-workers/contracts';

const workers = createServiceClient<typeof workersContract>({
  contract: workersContract,
  serviceName: 'workers-api',
  routerName: 'workers',
});

// triggerJob is served over /api/rpc/* and returns { jobId, triggered }.
// Over REST the {id} path segment carries the target job; over RPC (no path
// segment) it travels in this input object. Either way it resolves to
// input.id — with no id at all the call fails with a 422 VALIDATION_ERROR.
const { jobId, triggered } = await workers.triggerJob({
  id: 'process-payment',
  payload: { orderId: 'o_42', amountCents: 4999 },
});

// triggerTask is the polyglot-task twin, returning { taskId, triggered }.
const task = await workers.triggerTask({ id: 'validate-payload', payload: {} });

Graceful shutdown

Background runners must drain in flight work before they exit, or a redeploy loses jobs mid-run. The @netscript/plugin-workers-core/shutdown subpath provides a ShutdownManager that registers stoppable resources and stops them in priority order, with a timeout, when a shutdown is requested.

// plugins/workers/bin/with-shutdown.ts
import { ShutdownManager } from '@netscript/plugin-workers-core/shutdown';
import { startWorkers } from '@netscript/plugin-workers-core';

const runtime = await startWorkers({ autoStart: true });
const shutdown = new ShutdownManager({ timeoutMs: 10_000 });

// Register the runtime so a drain stops it gracefully (lower priority stops first).
shutdown.register({ id: 'workers-runtime', priority: 100, stop: (reason) => runtime.stop(reason) });

// Tie OS signals to the drain, then report what stopped / failed / timed out.
Deno.addSignalListener('SIGTERM', async () => {
  const report = await shutdown.shutdown('SIGTERM');
  console.info('shutdown', report.state, { stopped: report.stopped, timedOut: report.timedOut });
  Deno.exit(0);
});

Workers API & where jobs come from

Once Aspire is up and the schema is wired, the workers API on :8091 registers your job by id and exposes HTTP endpoints to seed, trigger, and inspect runs. These are the endpoints the CLI E2E suite validates live.

Observability: real job traces out of the box

Job-level observability is not a stub. The workers runtime instruments the scheduler → queue → worker → subprocess path with real OpenTelemetry spans, and those traces appear in the Aspire dashboard automatically once Aspire is up.

For spans you author inside a handler, import directly from @netscript/telemetry (e.g. @netscript/telemetry/instrumentation for withChildSpan). These nest correctly under the automatic dispatch span. See Observability for the model and Add OpenTelemetry for the recipe.

How it compares

Trigger.dev is a managed platform for background jobs and agent workflows; Temporal is a durable-execution system you self-host or rent as Temporal Cloud; NetScript's worker runtime is a plugin that lives inside your own repository and process tree. Each model carries a real tradeoff — a managed platform removes operations, a replay-based cluster gives the strongest durability guarantees, a local-first plugin keeps everything in code you own. The rows below are structural facts drawn from each project's public documentation (as of mid-2026), not rankings.

The practical consequence of the first two rows: a NetScript job handler is ordinary TypeScript with no replay-safety rules to learn, so code an agent writes for a service moves into a worker unchanged — the isolation question is deferred to the runner mode (the WORKER_RUNTIMES table above), a deployment setting rather than a handler concern.

Production notes

partial

Reference →

This hub is intentionally thin — the full generated API for @netscript/plugin-workers (defineJobHandler, the job/task builders, the runtime, the shutdown manager, and every exported type and subpath) lives in the reference.

workers