httk.workflow.runtime

Attempt identity and supervised commands.

The attempt context and run_command() are protocol-level facilities every native runner uses; the environment-binding helper below is what the authoring SDK and the Bash bridge both recover an attempt through.

Classes

AttemptContext

Describe the immutable identity and restart evidence for one running attempt.

CommandResult

Report the result of an argv-only supervised child process.

Functions

run_command(argv, *[, timeout, cwd, environment, ...])

Run an argv array and terminate its process group on timeout.

Module Contents

class httk.workflow.runtime.AttemptContext[source]

Describe the immutable identity and restart evidence for one running attempt.

Parameters:

  • workspace_id – Identify the workspace.

  • job_id – Identify the job.

  • job_key – Identify the job payload.

  • placement – Locate the job placement.

  • step – Identify the runner step.

  • activation_id – Identify the activation.

  • attempt_id – Identify the attempt.

  • activation_ordinal – Record the activation sequence position.

  • attempt_ordinal – Record the attempt sequence position.

  • total_attempts – Record the planned attempt count.

  • is_restart – Mark whether this attempt is a restart.

  • is_unclean_restart – Mark whether the restart followed an unclean exit.

  • attempt_reason – Explain why this attempt was selected.

  • previous_attempt_id – Identify the preceding attempt when present.

  • activation_reason – Explain why the activation was selected.

  • workdir_mode – Describe how the work directory was selected.

  • workdir_reused – Mark whether the work directory was reused.

  • unsafe_persistent_takeover – Record whether persistent takeover was enabled.

  • data_generation – Record the data generation at claim time.

  • durable – Record whether storage-crash durability was enabled.

  • settings – Record workspace application settings at claim time.

  • resources – Record the resources assigned to the attempt.

  • join – Record the job’s join description.

  • raw – Preserve the complete decoded context.

workspace_id: str[source]
job_id: str[source]
job_key: str[source]
placement: str[source]
step: str[source]
activation_id: str[source]
attempt_id: str[source]
activation_ordinal: int | None[source]
attempt_ordinal: int | None[source]
total_attempts: int | None[source]
is_restart: bool[source]
is_unclean_restart: bool[source]
attempt_reason: str | None[source]
previous_attempt_id: str | None[source]
activation_reason: str | None[source]
workdir_mode: str | None[source]
workdir_reused: bool[source]
unsafe_persistent_takeover: bool[source]
data_generation: int | None[source]
durable: bool[source]
settings: collections.abc.Mapping[str, object][source]
resources: collections.abc.Mapping[str, object][source]
join: object[source]
raw: collections.abc.Mapping[str, Any][source]
classmethod read(path)[source]

Read and validate a manager-written attempt context.

Parameters:

path (str | os.PathLike[str]) – Locate the attempt context file.

Returns:

The validated attempt context.

Raises:

ValueError – If the context format or required values are invalid.

Return type:

Self

class httk.workflow.runtime.CommandResult[source]

Report the result of an argv-only supervised child process.

Parameters:

  • argv – Preserve the command arguments that were run.

  • returncode – Record the child process return code.

  • stdout – Capture standard output.

  • stderr – Capture standard error.

  • timed_out – Mark whether the command exceeded its timeout.

argv: tuple[str, Ellipsis][source]
returncode: int[source]
stdout: bytes[source]
stderr: bytes[source]
timed_out: bool[source]
httk.workflow.runtime.run_command(argv, *, timeout=None, cwd=None, environment=None, termination_grace=10.0)[source]

Run an argv array and terminate its process group on timeout.

Parameters:
Returns:

The supervised command result.

Raises:

ValueError – If the command or timeout settings are invalid.

Return type:

CommandResult