wove.environment

wove.environment contains the executor contract and the runtime bridge that sends tasks to local, subprocess, or remote task environments.

When a named environment becomes running work, wove.environment defines the contract: executor instances, runtime delivery errors, and the interface custom executors use to plug into Wove.

Main Types

• EnvironmentExecutor: the four-method executor interface: start, send, recv, stop.

• LocalEnvironmentExecutor: in-process task execution.

• StdioEnvironmentExecutor: JSON-lines subprocess executor.

• HttpEnvironmentExecutor: direct HTTP/HTTPS network executor.

• GrpcEnvironmentExecutor: generic unary gRPC network executor.

• WebSocketEnvironmentExecutor: bidirectional WebSocket network executor.

• BackendAdapterEnvironmentExecutor: callback-based executor for backend adapters.

• ExecutorRuntime: multiplexes task execution across configured environments.

Public Exceptions

• MissingDispatchFeatureError: raised by dispatch-only executors when wove[dispatch] is not installed.

• EnvironmentExecutionError: wraps a normalized backend error payload.

• DeliveryTimeoutError: raised for delivery timeout or heartbeat expiry.

• DeliveryOrphanedError: raised when pending backend work is orphaned during shutdown handling.

Related Pages

• Executors: frame protocol, executor lifecycle, network executors, error payload shape, and cancellation behavior.

• Custom Executors: implementing the executor interface for project-owned transports.

• wove.security: network executor request signing and verification helpers.

• wove.backend: backend callback transport used by backend adapters.

API Details

class wove.environment.BackendAdapterEnvironmentExecutor(name, adapter_class=None, required_modules=None)

Bases: EnvironmentExecutor

Executor that submits Wove task payloads to a backend adapter and receives worker frames over a callback server.

Parameters:

• name (str)

• adapter_class (Type[BackendAdapter] | None)

• required_modules (Tuple[str, ...] | None)

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

exception wove.environment.DeliveryOrphanedError

Bases: RuntimeError

Raised when a backend run becomes orphaned during runtime shutdown/failure handling.

exception wove.environment.DeliveryTimeoutError

Bases: RuntimeError

Raised when backend delivery does not complete within configured delivery_timeout.

exception wove.environment.EnvironmentExecutionError(payload)

Bases: RuntimeError

Error raised when an executor reports a normalized error payload.

Parameters:

payload (Dict[str, Any])

Return type:

None

class wove.environment.EnvironmentExecutor

Bases: ABC

CGI-like stream transport contract for environment executors.

abstractmethod async recv()

Receive one event frame.

Return type:

Dict[str, Any]

abstractmethod async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

abstractmethod async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

abstractmethod async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.environment.ExecutorRuntime(environment_definitions, run_config)

Bases: object

Multiplexes task execution over environment executors.

Parameters:

• environment_definitions (Dict[str, Dict[str, Any]])

• run_config (Dict[str, Any])

async ensure_environment(environment_name, definition)

Parameters:

• environment_name (str)

• definition (Dict[str, Any])

Return type:

None

is_local_environment(environment_name)

Parameters:

environment_name (str)

Return type:

bool

async run_task(*, task_name, task_func, task_args, task_info)

Parameters:

• task_name (str)

• task_func (Any)

• task_args (Dict[str, Any])

• task_info (Dict[str, Any])

Return type:

Any

async start()

Return type:

None

async stop()

Return type:

None

class wove.environment.GrpcEnvironmentExecutor

Bases: EnvironmentExecutor

Network executor that sends Wove frames through a generic gRPC method.

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.environment.HttpEnvironmentExecutor(*, require_https=False)

Bases: EnvironmentExecutor

Network executor that sends Wove frames to a worker service over HTTP or HTTPS.

Parameters:

require_https (bool)

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.environment.LocalEnvironmentExecutor

Bases: EnvironmentExecutor

In-process executor implementation.

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.environment.StdioEnvironmentExecutor

Bases: EnvironmentExecutor

Subprocess JSON-lines stream executor.

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.environment.WebSocketEnvironmentExecutor

Bases: EnvironmentExecutor

Network executor that exchanges Wove frames with a worker service over WebSocket.

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

wove.environment.build_executor_from_name(name)

Parameters:

name (str)

Return type:

EnvironmentExecutor

wove.environment.coerce_executor(executor_value)

Parameters:

executor_value (Any)

Return type:

EnvironmentExecutor

wove.environment.normalize_exception(exc, *, source='task', retryable=False)

Parameters:

• exc (BaseException)

• source (str)

• retryable (bool)

Return type:

Dict[str, Any]