@netscript/plugin-workers-core

Job, task, workflow, runtime, config, and testing primitives for NetScript workers plugins. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

Background-job definitions fail in two places: at definition time, when a job is missing an execution target and nobody notices until production; and at runtime, when the executor and its storage are welded together and untestable. This package attacks both. defineJob, defineTask, and defineWorkflow are typestate-gated builders — build() only exists once an entrypoint or handler is set, so an incomplete definition is a compile error rather than a runtime surprise. The runtime composes from injected registry, worker, and storage ports with memory-backed defaults, so the same definitions run in production and in permission-free tests.

This is the core that the deployable @netscript/plugin-workers plugin binds to a NetScript host. Use it directly for custom hosts, libraries, and tests.

Job context cancellation

JobHandlerContext on the root surface and JobContext on the runtime surface carry a required signal: AbortSignal and optional deadlineAt: number (epoch milliseconds). JobDispatchContext accepts an optional caller signal; the InProcessJobRunner supplies a separate owned signal to the handler.

Pass the signal into downstream abort-aware APIs and check it at yielding checkpoints. Cleanup belongs in finally. See handler guidance and cleanup tuning. The Workers API runs router does not expose an operator cancel operation; caller signal cancellation here describes custom in-process dispatch, not an HTTP cancel endpoint. Other execution modes require their own propagation verification.

Exports

The package publishes eighteen entrypoints. The root path carries the authoring surface; the subpaths expose the runtime layers a host composes.

Export counts are the symbol counts deno doc reports for each entrypoint; the layered subpaths re-export shared vocabulary, so the counts overlap rather than sum.

Root surface (@netscript/plugin-workers-core)

Definition builders

Each builder is typestate-gated: build() becomes available only after the definition is complete.

Jobs and tasks both accept either an in-process handler or a runtime-specific entrypoint; workflows sequence their definitions. The three builders share the same typestate discipline.

Handler results and tools

JobTools is how a handler reaches telemetry without importing an SDK: the span operations it exposes are bound to the active worker instrumentation context.

Schedules and permissions

Runtime

Two entry styles for one runtime: root startWorkers() creates and starts the memory-backed preset, while root createWorkersRuntime() creates the same runtime without starting it. Import createWorkersRuntime from /runtime when registries, executors, storage, or other runtime ports must be injected explicitly.

Inspection

These are what CLI listings and doctor checks call: they read a definition and report on it without starting a runtime or touching storage.

Idempotency

Delivery is at-least-once with an applied-key guard window. A crash after an external effect and before marking it applied can repeat that effect; one effective application requires independently idempotent downstream persistence. A key is resolved from a caller-supplied key, the message id, or a payload hash — WorkerIdempotencySource records which — and then claimed against the port before the effect runs.

Related pages

• @netscript/plugin-workers — the deployable plugin that binds this core to a NetScript host.
• @netscript/plugin-triggers-core — trigger handlers enqueue these jobs through enqueueJob.
• @netscript/plugin-sagas-core — its integration/workers helpers dispatch jobs and tasks from saga cascades.
• @netscript/plugin-streams-core — the producer behind the projected execution stream.

Back to the reference overview.

Checked command sink

Register branded job/task targets with createWorkerCommandOutboxSink; delivery topic selects the copied allowlist entry. The existing supplied trigger receives the stable dedupe key, correlation and W3C. A receipt is checked for the selected kind/id, nonempty run identity and valid acceptance time before normalization. Missing, malformed, mismatched and bare status responses cannot settle. No queue or progress protocol is added. Cancellation is cooperative. The relay publication-to-mark window and worker effect-to-applied-marker window both permit redelivery; downstream work must be independently idempotent. Construction needs no permissions; supplied clients own theirs.

Runtime-schema tasks

defineTask(id).payload(selectedSchema).handler(...).build() preserves the selected schema's payload type and validates input before the task handler. The legacy .payload<T>() overload keeps ordinary task compatibility but provides no runtime schema; durable saga worker-task effects refuse it. These task effects use the same selected-definition payload validation as job effects.

KV retention

Each job's retention.kvRetentionDays (default 3) bounds terminal execution records under workers/executions. The execution state store and the registry execution-write port both set KV expireIn from completedAt; rewriting a result or progress record does not extend that deadline. Pending, queued, and running executions remain durable while they are open. An explicit archiveToDb: false never causes a database archive in these KV write or cleanup paths.

DELETE /cleanup now deletes expired terminal execution records instead of returning a stubbed success. It inspects at most 1000 entries per call and advances to the next page on later calls. Atomic version checks prevent it from deleting a record updated after inspection. Fresh terminal records and open executions are preserved. This endpoint also removes legacy execution records written without TTL; normal new-record expiry is performed by the KV backend and needs no app session. Job/task definitions remain configuration rather than expiring execution history.

Exports: discovery metadata

The @netscript/plugin-workers-core/discovery entrypoint (./src/builders/discovery.ts) exports NETSCRIPT_CONTRIBUTION_BUILDERS. Pass these immutable patterns through the plugin SDK additionalBuilders option. The CLI composes first-party metadata before walking the project, so single-plugin updates succeed regardless of workers/streams order.