cayu.runners.base

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

attach_cancellation_artifacts

from cayu.runners import attach_cancellation_artifacts

Attach runner cleanup diagnostics to a cancellation out-of-band.

Substituting an exception subclass for the in-flight CancelledError discards the exception instance asyncio saved for the awaiting task. Instead runners record diagnostics on the original exception’s artifacts attribute and re-raise it unchanged; the runtime reads the attribute via getattr.

attach_cancellation_artifacts(exc: BaseException, artifacts: list[dict[str, Any]]) -> None

Release source · Runtime guarantees · Capability guides

copy_exec_command

from cayu.extensions.runners import copy_exec_command

Return a detached, revalidated exact ExecCommand snapshot.

copy_exec_command(command: ExecCommand) -> ExecCommand

Release source · Runtime guarantees · Capability guides

DEFAULT_EXEC_OUTPUT_LIMIT_BYTES

from cayu.runners import DEFAULT_EXEC_OUTPUT_LIMIT_BYTES

DEFAULT_EXEC_OUTPUT_LIMIT_BYTES = 1024 * 1024

Release source · Runtime guarantees · Capability guides

ExecCommand

from cayu.runners import ExecCommand

Command to execute.

argv is the default safe process form. shell is reserved for explicit shell scripts where parsing, expansion, and quoting are intentional.

Bases: _CommandValidationModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
kind	Literal['process', 'shell']	'process'
argv	list[str] | None	None
shell	str | None	None

model_validate (method)

ExecCommand.model_validate(obj: Any, *, strict: bool | None=None, extra: Any=None, from_attributes: bool | None=None, context: Any | None=None, by_alias: bool | None=None, by_name: bool | None=None) -> Self

model_validate_json (method)

ExecCommand.model_validate_json(json_data: str | bytes | bytearray, *, strict: bool | None=None, extra: Any=None, context: Any | None=None, by_alias: bool | None=None, by_name: bool | None=None) -> Self

model_validate_strings (method)

ExecCommand.model_validate_strings(obj: Any, *, strict: bool | None=None, extra: Any=None, context: Any | None=None, by_alias: bool | None=None, by_name: bool | None=None) -> Self

init (method)

ExecCommand.__init__(**data: Any) -> None

copy_argv (method)

ExecCommand.copy_argv(value: list[str] | None) -> list[str] | None

process (method)

ExecCommand.process(*argv: str) -> ExecCommand

bash (method)

ExecCommand.bash(script: str) -> ExecCommand

validate_shape (method)

ExecCommand.validate_shape() -> ExecCommand

Release source · Runtime guarantees · Capability guides

ExecResult

from cayu.runners import ExecResult

Observed command outcome, including bounded capture and full byte totals.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
stdout	str	''
stderr	str	''
exit_code	StrictInt	0
timed_out	StrictBool	False
cancelled	StrictBool	False
stdout_truncated	StrictBool	False
stderr_truncated	StrictBool	False
stdout_bytes	StrictInt | None	Field(default=None, ge=0)
stderr_bytes	StrictInt | None	Field(default=None, ge=0)
artifacts	list[dict]	Field(default_factory=list)

copy_artifacts (method)

ExecResult.copy_artifacts(value: list[dict]) -> list[dict]

Release source · Runtime guarantees · Capability guides

RemoteWorkspaceBranchCapability

from cayu.runners import RemoteWorkspaceBranchCapability

Explicit provider proof for the durable guest branch protocol.

Merely being able to execute Python or reconnect to a runner is not this capability. An exact runner adapter opts in only after verifying that its allocation filesystem retains branch state across Cayu process loss and supports the guest-side cooperative publication guard.

Bases: RunnerWorkspaceCapability.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
protocol_version	class attribute	'cayu-runner-workspace-branch-v1'

resource_key (property)

RemoteWorkspaceBranchCapability.resource_key() -> tuple[object, ...]

Stable identity of the sandbox that backs this capability.

allocation_fingerprint (property)

RemoteWorkspaceBranchCapability.allocation_fingerprint() -> str

Privacy-safe stable identity for the retained remote allocation.

Release source · Runtime guarantees · Capability guides

Runner

from cayu.runners import Runner

Executes commands/code in a workspace or sandbox.

Shared lifecycle contract:

• system_execution_mode declares whether exec_system() intentionally shares the ordinary command lane or selects a separate trusted lane. Runner wrappers must preserve both the declaration and dispatch.
• close() applies the adapter’s configured lifecycle action once; further exec calls fail.
• Interrupted commands (cancellation/timeout) run cleanup. When command cleanup cannot confirm the command stopped, the exec path latches shut (_close_exec) so an unknown still-running command cannot race new work.
• Inconclusive remote command cleanup permanently poisons execution on that runner instance. reopen_exec() clears only an intentional fence, not uncertainty from failed cleanup.
• close() is terminal for command execution, even for adapters whose configured close action intentionally leaves a remote sandbox alive.

Bases: ABC.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
isolation	str	'unknown'
default_cwd	str	'/'
system_execution_mode	RunnerSystemExecutionMode	'shared'

workload_authority (method)

Runner.workload_authority(name: str) -> RunnerWorkloadAuthority | None

Return runner-owned authority for an exact provisioned workload.

execution_environment_authority (method)

Runner.execution_environment_authority() -> ExecutionEnvironmentAuthority

Return the exact environment boundary that owns this runner.

output_secret_values_present (method)

Runner.output_secret_values_present() -> bool | None

Report whether command output can contain runner-owned secret values.

None is fail-closed unknown authority. Wrappers must merge their own secret registry with the wrapped runner’s declaration.

browser_control_endpoint_reachable (method)

Runner.browser_control_endpoint_reachable(endpoint: str) -> bool | None

Report whether the guest can dial a browser control or recording endpoint.

None makes no declaration: reachability then rests on deployment configuration, as with Docker’s colocated control-server alias. A runner whose guest has a fixed, verified control path returns False for every endpoint outside it, so no control credential is sent there.

browser_recording_supported (method)

Runner.browser_recording_supported() -> bool

Declare that this runner captures and finalizes browser recordings.

execution_profile_identity (property)

Runner.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return a stable application declaration, or None when non-portable.

preflight_exec (method)

Runner.preflight_exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> None

Validate one complete request without lookup, dispatch, or mutation.

Wrappers call this seam before consulting invocation-scoped secret state or admitting managed workspace work. Backends with stricter transport rules override it and must remain side-effect free.

exec (method)

async Runner.exec(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Execute a command and return stdout/stderr/exit metadata.

exec_redacted (method)

async Runner.exec_redacted(command: ExecCommand, *, redactor: SecretRedactor, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Execute with an invocation redactor at the closest supported boundary.

Bundled runners override this to redact while capturing. The default preserves compatibility for custom runners but treats a channel that was already truncated as irrecoverably ambiguous and omits its text.

exec_system (method)

async Runner.exec_system(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: str | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Execute a control-plane lifecycle command on the declared system lane.

close (method)

async Runner.close() -> None

Release the runner. The default implementation only marks it closed.

await_pending_command_settlement (method)

async Runner.await_pending_command_settlement() -> bool

Wait for command cleanup deferred beyond an exec result.

Return True only when every command-cleanup operation dispatched before this call has positively reached its terminal boundary. This hook is consulted only after a runner explicitly reports deferred cleanup. Such runners must override it; the default fails closed so an unknown extension cannot turn absence of evidence into quiescence.

refresh_execution_admission (method)

async Runner.refresh_execution_admission() -> None

Re-probe live admission evidence when supported by this runner.

The default makes no new claim. A supporting implementation may renew only the exact runner represented by its current admission candidate; it must not replace the environment, immutable image, or toolchain identity. It must also settle every dispatched probe, or transfer an authenticated settlement owner, before returning or raising. Callers must re-read and validate the complete candidate after this hook; requesting renewal never authorizes execution by itself.

execution_admission_candidate (method)

Runner.execution_admission_candidate() -> ExecutionAdmissionCandidate | None

Return explicit provider-neutral admission evidence, when implemented.

The default deliberately makes no capability claim. Runtimes must fail closed when a workload requires evidence that its selected runner does not provide.

collect_execution_admission_candidate (method)

async Runner.collect_execution_admission_candidate() -> ExecutionAdmissionCandidate | None

Collect final evidence after lifecycle-owned mutating setup completes.

The default adapts existing side-effect-free snapshot implementations. Runners whose evidence depends on live external state override this hook and complete or positively transfer settlement ownership for every dispatched probe before returning or raising for any reason.

execution_admission_candidate_for (method)

Runner.execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate | None

Read evidence for an explicit, caller-owned requirement set.

This snapshot must not dispatch work or mutate a shared probe plan. The default reads the runner’s existing candidate and makes no new claim from the supplied requirements alone.

execution_admission_observer (method)

Runner.execution_admission_observer(requirements: ExecutionRequirements) -> RunnerExecutionAdmissionObserver

Create a request-scoped evidence owner for this exact runner.

Creation is side-effect-free. The lifecycle owns collection, renewal, and any transferred settlement tasks; the observer cannot admit work.

collect_execution_admission_candidate_for (method)

async Runner.collect_execution_admission_candidate_for(requirements: ExecutionRequirements) -> ExecutionAdmissionCandidate | None

Collect final request-bound evidence under lifecycle ownership.

Requirements are input, never proof. Implementations must isolate concurrent requirement sets and settle or positively transfer every dispatched probe under the same contract as the ordinary collector.

resource_key (property)

Runner.resource_key() -> tuple[object, ...] | None

Stable identity of the runner-owned execution resource, when known.

is_closed (property)

Runner.is_closed() -> bool

Whether terminal runner finalization has completed.

lifecycle_state (property)

Runner.lifecycle_state() -> RunnerLifecycleState

Observe execution eligibility without exposing provider internals.

workspace_capability (method)

Runner.workspace_capability(capability_type: type[RunnerWorkspaceCapabilityT]) -> RunnerWorkspaceCapabilityT | None

Return a narrow native-workspace capability, when supported.

The returned object has no lifecycle methods. Callers must continue to finalize the owning runner or environment; they cannot close an unmanaged provider runner through this composition path.

binary_stream_capability (method)

Runner.binary_stream_capability() -> RunnerBinaryStreamCapability | None

Return bounded binary execution when its support is already known.

Discovery must not provision a runner or execute commands. Wrappers with an unknown target return None until support is established, so workspace transfers can retain their text transport fallback. Returned capabilities must preserve the owning runner’s execution fences.

reopen_exec (method)

Runner.reopen_exec() -> None

Clear an intentional execution fence on an otherwise-open runner.

This is not recovery authority for inconclusive command cleanup. Poisoned instances cannot be reopened, including after a late cleanup acknowledgement; a new independently verified allocation owner is needed.

resolve_cwd (method)

Runner.resolve_cwd(cwd: str | None=None) -> str

Resolve a requested cwd to a canonical path inside the runner root.

Relative requests are resolved against default_cwd. An absolute input is accepted only when it is already contained by the runner root, making canonicalization idempotent for policy-authorized execution.

aenter (method)

async Runner.__aenter__() -> Self

aexit (method)

async Runner.__aexit__(exc_type: Any, exc_val: Any, exc_tb: Any) -> bool

Release source · Runtime guarantees · Capability guides

RunnerBinaryStreamCapability

from cayu.runners import RunnerBinaryStreamCapability

Nominal runner capability for bounded binary standard-I/O transfers.

Binary streams are control-plane transport inputs and outputs. Implementations consume from and write to the caller-owned objects without closing them and must settle every delegated read, write, and child process before returning, including after cancellation or timeout. Paths are deliberately not accepted: remote adapters receive bytes through their transport, never host filenames.

Bases: ABC.

exec_stream (method)

async RunnerBinaryStreamCapability.exec_stream(command: ExecCommand, *, cwd: str | None=None, env: dict[str, str] | None=None, env_remove: tuple[str, ...]=(), timeout_s: int | None=None, stdin: BinaryIO | None=None, stdout: BinaryIO | None=None, stdout_limit_bytes: int | None=None, output_limit_bytes: int | None=DEFAULT_EXEC_OUTPUT_LIMIT_BYTES) -> ExecResult

Execute with optional binary stdin/stdout streams.

stdout_limit_bytes is a hard capture limit for the binary channel. Bytes beyond it are drained but not written and set stdout_truncated. Text stderr remains redacted and bounded by output_limit_bytes.

Release source · Runtime guarantees · Capability guides

RunnerExecutionAdmissionObserver

from cayu.runners import RunnerExecutionAdmissionObserver

One exact runner/requirement observation lifetime, never admission authority.

Extensions may retain bounded evidence in a request-local state object. Every dispatched observation must settle or transfer authenticated cleanup ownership before returning or raising, including cancellation and timeout.

Decorators: @dataclass(frozen=True, slots=True, repr=False).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
runner	Runner	required
requirements	ExecutionRequirements	required

snapshot (method)

RunnerExecutionAdmissionObserver.snapshot() -> ExecutionAdmissionCandidate | None

Read exact evidence without dispatching an external operation.

collect (method)

async RunnerExecutionAdmissionObserver.collect() -> ExecutionAdmissionCandidate | None

Observe after binding/setup has selected the exact final runner.

refresh (method)

async RunnerExecutionAdmissionObserver.refresh() -> None

Renew evidence without replacing this observer’s runner or requirements.

Release source · Runtime guarantees · Capability guides

RunnerExecutionError

from cayu.runners import RunnerExecutionError

A fixed-message command failure with typed, secret-safe evidence.

Bases: RuntimeError.

init (method)

RunnerExecutionError.__init__(*, diagnostic: dict[str, Any]) -> None

Release source · Runtime guarantees · Capability guides

RunnerLifecycleState

from cayu.runners import RunnerLifecycleState

RunnerLifecycleState = Literal['reusable', 'fenced', 'poisoned', 'closing', 'closed']

Release source · Runtime guarantees · Capability guides

RunnerSystemExecutionMode

from cayu.runners import RunnerSystemExecutionMode

RunnerSystemExecutionMode = Literal['shared', 'separate']

Release source · Runtime guarantees · Capability guides

RunnerUnavailableError

from cayu.runners import RunnerUnavailableError

A runner cannot execute commands until it is reconnected or replaced.

Bases: RuntimeError.

init (method)

RunnerUnavailableError.__init__(message: str, *, diagnostic: Mapping[str, Any]) -> None

Release source · Runtime guarantees · Capability guides

RunnerWorkloadAuthority

from cayu.runners import RunnerWorkloadAuthority

Runner-owned identity for one provisioned image workload.

Higher layers may compare this value with an exact workload they support, but runners never need to import those higher-layer tools to declare what is installed in their selected image.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
name	str	required
image	str	required
command	tuple[str, ...]	required
protocol_version	str	required
worker_version	str	required
component_versions	tuple[tuple[str, str], ...]	()

Release source · Runtime guarantees · Capability guides

RunnerWorkspaceCapability

from cayu.runners import RunnerWorkspaceCapability

Narrow provider capability used by a first-party native workspace.

Capability objects deliberately do not own runner lifecycle. A managed runner can therefore expose native filesystem behavior without exposing the raw provider runner or a second close() authority.

Bases: ABC.

resource_key (property)

RunnerWorkspaceCapability.resource_key() -> tuple[object, ...]

Stable identity of the sandbox that backs this capability.

Release source · Runtime guarantees · Capability guides