cayu.runners definitions

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.

`cleanup_runner_command_with_diagnostic`

from cayu.extensions.runners import cleanup_runner_command_with_diagnostic

Run one bounded interruption cleanup and describe its outcome.

"command" awaits handle.kill(), "sandbox" awaits sandbox.kill() (and asks the runner to close), and "none" records a skipped receipt. A missing handle or kill method is unsupported, kill() returning False or raising is failed, and exceeding timeout_s is timeout; only an awaited, non-False kill is completed. Ordinary exceptions from kill() become evidence rather than propagating.

async cleanup_runner_command_with_diagnostic(sandbox: Any, *, handle: Any | None, adapter: str, timeout_s: float, policy: RunnerCleanupPolicy) -> RunnerCleanupResult

Release source · Runtime guarantees · Capability guides

`copy_runner_env`

from cayu.extensions.runners import copy_runner_env

Validate and copy a command environment.

With inherit_env=False (what sandbox runners use) the host process environment is never included; only the explicit env entries are.

copy_runner_env(env: dict[str, str] | None, *, inherit_env: bool, case_sensitive: bool=True) -> dict[str, str]

Release source · Runtime guarantees · Capability guides

`DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS`

from cayu.extensions.runners import DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS

DEFAULT_RUNNER_CANCEL_TIMEOUT_SECONDS = 5.0

Release source · Runtime guarantees · Capability guides

`DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY`

from cayu.runners import DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY

DEFAULT_RUNNER_CANCELLATION_CLEANUP_POLICY: RunnerCleanupPolicy = 'command'

Release source · Runtime guarantees · Capability guides

`DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY`

from cayu.runners import DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY

DEFAULT_RUNNER_TIMEOUT_CLEANUP_POLICY: RunnerCleanupPolicy = 'command'

Release source · Runtime guarantees · Capability guides

`redact_completed_exec_result`

from cayu.extensions.runners import redact_completed_exec_result

Project a complete runner result through a safe compatibility boundary.

redact_completed_exec_result(result: object, *, redactor: SecretRedactor, output_limit_bytes: int | None, omit_pretruncated: bool)

Release source · Runtime guarantees · Capability guides

`RedactedOutputCapture`

from cayu.extensions.runners import RedactedOutputCapture

Capture a bounded redacted head while counting original input bytes.

init (method)

RedactedOutputCapture.__init__(*, redactor: SecretRedactor, limit: int | None) -> None

append (method)

RedactedOutputCapture.append(chunk: str | bytes) -> None

seed_if_empty (method)

RedactedOutputCapture.seed_if_empty(chunk: object) -> None

replace (method)

RedactedOutputCapture.replace(chunk: bytes) -> None

finish_complete (method)

RedactedOutputCapture.finish_complete() -> None

abort (method)

RedactedOutputCapture.abort() -> None

text (method)

RedactedOutputCapture.text() -> str

Release source · Runtime guarantees · Capability guides

`register_runner_adapter_identity`

from cayu.extensions.runners import register_runner_adapter_identity

Trust one runner adapter name, and optional error class names, process-wide.

name must be a lowercase ASCII slug (letters, digits, single hyphens, starting with a letter, at most 63 characters) and must not be "unknown". Each trusted error type must be a Python identifier of at most 128 characters; at most 64 may be registered per adapter.

Registering the same name again with the same error-type set returns the existing identity. Registering it with a different set raises ValueError; built-in identities cannot be widened. Registration cannot be undone for the life of the process.

register_runner_adapter_identity(name: str, *, trusted_error_types: Iterable[str]=()) -> RunnerAdapterIdentity

Release source · Runtime guarantees · Capability guides

`registered_runner_adapter_identities`

from cayu.extensions.runners import registered_runner_adapter_identities

Return a read-only snapshot of every registered identity, including built-ins.

registered_runner_adapter_identities() -> Mapping[str, RunnerAdapterIdentity]

Release source · Runtime guarantees · Capability guides

`remove_runner_env`

from cayu.extensions.runners import remove_runner_env

Return an environment without explicitly forbidden variables.

remove_runner_env(environment: dict[str, str], keys: tuple[str, ...], *, case_sensitive: bool=True) -> dict[str, str]

Release source · Runtime guarantees · Capability guides

`RUNNER_CLEANUP_ARTIFACT_TYPE`

from cayu.extensions.runners import RUNNER_CLEANUP_ARTIFACT_TYPE

RUNNER_CLEANUP_ARTIFACT_TYPE = 'cayu.runner_cleanup.v1'

Release source · Runtime guarantees · Capability guides

`RunnerAdapterIdentity`

from cayu.extensions.runners import RunnerAdapterIdentity

One registered runner adapter identity.

name is the value published as adapter in runner diagnostics and cleanup receipts. trusted_error_types are additional exception class names that the adapter asked Cayu to publish verbatim instead of the generic "Exception" classification. Built-in identities carry no extra names because their SDK exception names are part of the runtime baseline.

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`
`trusted_error_types`	`frozenset[str]`	`frozenset()`

Release source · Runtime guarantees · Capability guides

`RunnerCleanupPolicy`

from cayu.runners import RunnerCleanupPolicy

RunnerCleanupPolicy = Literal['command', 'sandbox', 'none']

Release source · Runtime guarantees · Capability guides

`RunnerCleanupResult`

from cayu.extensions.runners import RunnerCleanupResult

One cleanup receipt plus whether the runner’s exec path must close.

artifact is the cayu.runner_cleanup.v1 receipt for the phase just settled; preceding_artifacts holds receipts from earlier phases in order. failure, when present, is the cleanup failure that must remain attached to the caller’s outcome.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`artifact`	`dict[str, Any]`	`required`
`close_runner`	`bool`	`required`
`preceding_artifacts`	`tuple[dict[str, Any], ...]`	`()`
`failure`	`BaseException \| None`	`None`

artifacts (property)

RunnerCleanupResult.artifacts() -> list[dict[str, Any]]

Release source · Runtime guarantees · Capability guides

`validate_cancel_timeout`

from cayu.extensions.runners import validate_cancel_timeout

Return a positive finite cleanup bound, defaulting None to five seconds.

validate_cancel_timeout(timeout_s: float | None) -> float

Release source · Runtime guarantees · Capability guides

`validate_output_limit`

from cayu.extensions.runners import validate_output_limit

Accept None or a positive int per-stream capture limit in bytes.

validate_output_limit(output_limit_bytes: int | None) -> int | None

Release source · Runtime guarantees · Capability guides

`validate_runner_cleanup_policy`

from cayu.extensions.runners import validate_runner_cleanup_policy

Accept only "command", "sandbox", or "none".

validate_runner_cleanup_policy(policy: RunnerCleanupPolicy, field_name: str) -> RunnerCleanupPolicy

Release source · Runtime guarantees · Capability guides

`validate_stdin`

from cayu.extensions.runners import validate_stdin

Accept None or text without Unicode surrogates (NUL is allowed).

validate_stdin(stdin: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

`validate_timeout`

from cayu.extensions.runners import validate_timeout

Accept None or a positive int command timeout in seconds.

validate_timeout(timeout_s: int | None) -> int | None

Release source · Runtime guarantees · Capability guides