cayu.workspaces.runner

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.

DEFAULT_RUNNER_WORKSPACE_LIST_LIMIT

from cayu.workspaces import DEFAULT_RUNNER_WORKSPACE_LIST_LIMIT

DEFAULT_RUNNER_WORKSPACE_LIST_LIMIT = 500

Release source · Runtime guarantees · Capability guides

DEFAULT_RUNNER_WORKSPACE_READ_LIMIT_BYTES

from cayu.workspaces import DEFAULT_RUNNER_WORKSPACE_READ_LIMIT_BYTES

DEFAULT_RUNNER_WORKSPACE_READ_LIMIT_BYTES = 256 * 1024

Release source · Runtime guarantees · Capability guides

RunnerWorkspace

from cayu.workspaces import RunnerWorkspace

Workspace whose descriptor-guarded file operations execute through a runner.

The configured cwd is trusted operator input. Each operation pins that root and opens every guest-controlled component relative to the preceding directory descriptor with O_NOFOLLOW. Within one traversal, an opened descriptor authorizes that inode even if another guest process later relocates it. Multi-pass operations start each later traversal from the pinned root and reject replacement symlinks. Guests without the required POSIX descriptor-relative primitives fail closed.

Bases: WorkspaceDirectoryPruner, RunnerBoundWorkspace, BoundedTarReader, TarWriter, BoundedTarStreamReader, TarStreamWriter.

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
id	str	required

prune_empty_directories (method)

async RunnerWorkspace.prune_empty_directories(path: str, *, max_directories: int) -> None

reference_binding (method)

RunnerWorkspace.reference_binding() -> WorkspaceReferenceBinding

Bind application data to this workspace incarnation.

The default is object-lifetime scoped and fails closed after reopening. Durable adapters may override this method only when they can preserve an incarnation across recovery and rotate it on replacement. Never restore a generation from the application reference being validated.

read_bytes (method)

async RunnerWorkspace.read_bytes(path: str, *, offset: int=0, max_bytes: int | None=None) -> WorkspaceReadResult

bounded_read_limit (method)

RunnerWorkspace.bounded_read_limit(max_bytes: int) -> int

write_bytes (method)

async RunnerWorkspace.write_bytes(path: str, content: bytes) -> None

delete (method)

async RunnerWorkspace.delete(path: str) -> None

create_bytes (method)

async RunnerWorkspace.create_bytes(path: str, content: bytes) -> WorkspaceMutationResult

replace_bytes (method)

async RunnerWorkspace.replace_bytes(path: str, content: bytes, *, expected_revision: str) -> WorkspaceMutationResult

delete_if_revision (method)

async RunnerWorkspace.delete_if_revision(path: str, *, expected_revision: str) -> WorkspaceMutationResult

require_absent (method)

async RunnerWorkspace.require_absent(path: str) -> None

move_if_revision (method)

async RunnerWorkspace.move_if_revision(source_path: str, destination_path: str, *, expected_source_revision: str, require_destination_absent: bool=True) -> WorkspaceMoveResult

list (method)

async RunnerWorkspace.list(pattern: str='**/*', *, limit: int | None=None) -> WorkspaceListResult

list_git_entries (method)

async RunnerWorkspace.list_git_entries(*, limit: int) -> WorkspaceGitEntryListResult

resource_key (property)

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

tar_copy_policy_identity (method)

RunnerWorkspace.tar_copy_policy_identity() -> tuple[object, ...]

bounded_tar_stream_reader (method)

RunnerWorkspace.bounded_tar_stream_reader() -> BoundedTarStreamReader | None

tar_stream_writer (method)

RunnerWorkspace.tar_stream_writer() -> TarStreamWriter | None

branch_capabilities (method)

RunnerWorkspace.branch_capabilities() -> WorkspaceBranchCapabilities

branch_lifecycle_summary (method)

RunnerWorkspace.branch_lifecycle_summary() -> WorkspaceBranchLifecycleSummary

create_branch (method)

async RunnerWorkspace.create_branch(request: WorkspaceBranchRequest) -> WorkspaceBranchCreationResult

is_bound_to_runner (method)

RunnerWorkspace.is_bound_to_runner(runner: Runner) -> bool

runner_cwd (property)

RunnerWorkspace.runner_cwd() -> str

bound_runner_resource_key (property)

RunnerWorkspace.bound_runner_resource_key() -> tuple[object, ...] | None

read_tar_bytes (method)

async RunnerWorkspace.read_tar_bytes(paths: Sequence[str], *, max_file_bytes: int | None=None, max_total_bytes: int | None=None, max_archive_bytes: int | None=None) -> bytes

Read many workspace files in one runner exec as an uncompressed tar.

This is the bulk-transfer fast path used by SyncBinding: one guest process archives every requested file instead of one exec per file. Each file is capped at max_file_bytes (default_read_limit_bytes when omitted), and their combined logical size is capped at max_total_bytes when provided. An oversized transfer fails before the guest allocates the tar buffer. max_archive_bytes independently caps the conservative size of the raw tar, including framing and path metadata.

write_tar_bytes (method)

async RunnerWorkspace.write_tar_bytes(data: bytes) -> None

Write many workspace files in one runner exec from an uncompressed tar.

Members must be regular files with workspace-relative paths; symlink, absolute, and .. members are rejected inside the guest. Every member and its content is validated before the first file mutation.

read_tar_stream (method)

async RunnerWorkspace.read_tar_stream(paths: Sequence[str], destination: BinaryIO, *, max_file_bytes: int | None=None, max_total_bytes: int | None=None, max_archive_bytes: int | None=None) -> TarStreamReadResult

Stream one preflight-bounded uncompressed tar into a private sink.

write_tar_stream (method)

async RunnerWorkspace.write_tar_stream(source: BinaryIO, *, archive_bytes: int) -> None

Stream a tar through runner stdin and spool it privately in the guest.

init (method)

RunnerWorkspace.__init__(runner: Runner, *, cwd: str | None=None, workspace_id: str | None=None, python_executable: str='python3', default_read_limit_bytes: int=DEFAULT_RUNNER_WORKSPACE_READ_LIMIT_BYTES, default_list_limit: int=DEFAULT_RUNNER_WORKSPACE_LIST_LIMIT, excluded_directory_names: Iterable[str]=(), excluded_path_patterns: Iterable[str]=(), enable_workspace_branches: bool=False, branch_operation_timeout_s: int=300, branch_authority_resolver: WorkspaceBranchBindingAuthorityProvider | None=None) -> None

recover_branch (method)

async RunnerWorkspace.recover_branch(request: WorkspaceBranchRecoveryRequest) -> WorkspaceBranchRecoveryResult

capture_content_manifest (method)

async RunnerWorkspace.capture_content_manifest(*, max_paths: int, max_file_bytes: int, max_total_bytes: int) -> WorkspaceContentManifest

Hash the complete guarded workspace in one bounded guest operation.

Release source · Runtime guarantees · Capability guides