Execution contracts

See Customize the SDK for hook ordering, ownership, and implementation obligations. RunRequest describes one command. Executor contracts let adapters use a custom backend.

Public command values and execution contracts for integrations.

class contree_sdk.execution.RunRequest(*, command=None, shell=None, args=(), env=None, cwd=None, stdin=None, stdin_open=False, files=None, timeout=None, disposable=False, truncate_output_at=None, preserve_env=False, hostname=None, uid=None, gid=None, resources_limits=None, networking=None)

Command configuration passed through the session’s public extension hooks.

Use dataclasses.replace to change a request. Arguments and environment are copied at construction. File sources and stdin remain caller-owned. Exactly one of command and shell must be supplied. Results are saved by default; use disposable=True to leave session history unchanged.

command: str | None = None

shell: str | None = None

args: tuple[str, ...] = ()

env: Mapping[str, str] | None = None

cwd: str | None = None

stdin: Optional[Union[str, bytes, Path, Readable[str], Readable[bytes], AsyncReadable[str], AsyncReadable[bytes]]] = None

stdin_open: bool = False

files: list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None = None

timeout: float | timedelta | None = None

disposable: bool = False

truncate_output_at: int | None = None

preserve_env: bool = False

hostname: str | None = None

uid: int | None = None

gid: int | None = None

resources_limits: InstanceResourcesLimits | None = None

networking: InstanceNetworking | None = None

property title: str

property timeout_seconds: float | None

class contree_sdk.execution.OperationContext(request, session_id, image_uuid, parent_id, branch, files=(), attachments=(), detached=False, node_id=<factory>, created_at=<factory>, position_version=0, session_cwd=None, session_env=<factory>)

The effective request and history position captured before remote execution.

request: RunRequest

session_id: str

image_uuid: str

parent_id: str | None

branch: str | None

files: tuple[str, ...] = ()

attachments: tuple[StagedFile, ...] = ()

detached: bool = False

node_id: str

created_at: float

position_version: int = 0

session_cwd: str | None = None

session_env: Mapping[str, str]

class contree_sdk.execution.SyncExecutor

Execution and file access required by synchronous framework adapters.

Implementations own their lifecycle. Adapters do not close executors. Successful execution returns the client’s InstanceResult, including nonzero exit codes. read_file returns exact bytes or raises a client API exception.

session_id: str

abstractmethod execute(request)

Return type:

InstanceResult

abstractmethod read_file(path)

Return type:

bytes

write_file(path, content)

Write bytes to an absolute path, creating its parent directories.

Returns after the write is applied to the executor’s filesystem. It does not merely stage a file or upload a blob. Persistence follows execute(). The default runs mkdir and cat through execute() with binary stdin. Override this method to use another file-transfer mechanism. An override must coordinate with the executor’s commands and snapshot lifecycle.

Invalid paths raise ValueError; a failed write raises FileWriteError. Transport errors, timeouts, and cancellation propagate unchanged.

Return type:

None

class contree_sdk.execution.AsyncExecutor

Native asynchronous execution and file access for framework adapters.

session_id: str

abstractmethod async execute(request)

Return type:

InstanceResult

abstractmethod async read_file(path)

Return type:

bytes

async write_file(path, content)

Write bytes with the same contract as SyncExecutor.write_file.

The default awaits execute() with binary stdin. Override with native async file transfer, coordinating with commands and snapshot lifecycle. Returns after application, not after staging or blob upload. Invalid paths raise ValueError; a failed write raises FileWriteError. Transport errors, timeouts, and cancellation propagate unchanged.

Return type:

None

Public lifecycle contracts for operation and subprocess implementations.

class contree_sdk.session.contracts.SubprocessContract

Waitable event stream for one subprocess. Iteration and wait share completion state.

spid: int

abstractmethod wait(*, timeout=None)

Return type:

InstanceResult

abstractmethod pipe_to(*, stdout=None, stderr=None)

Return type:

InstanceResult

class contree_sdk.session.contracts.AsyncSubprocessContract

Waitable event stream for one subprocess. Iteration and wait share completion state.

spid: int

abstractmethod async wait(*, timeout=None)

Return type:

InstanceResult

abstractmethod async pipe_to(*, stdout=None, stderr=None)

Return type:

InstanceResult

class contree_sdk.session.contracts.OperationContract

An operation lifecycle. wait stores response before returning; cleanup preserves primary errors.

uuid: str

context: OperationContext | None

response: OperationResponse | None

abstractmethod apply_files(files)

Return type:

None

add_observer(observer)

Register an observer before starting the shared operation reader.

A None event marks EOF, with an optional stream error. Observers must not consume events or wait for this operation. Implementations without this optional facility reject registration.

Return type:

None

abstractmethod events(*, since=None, spid=None, timeout=None)

Return type:

Iterator[OperationEvent]

abstractmethod status(*, inflight=False)

Return type:

OperationResponse

abstractmethod send_stdin(data, *, spid=1, close=True)

Return type:

None

abstractmethod pipe_stdin(chunks, *, spid=1, close=True, chunk_size=65536)

Return type:

StdinResult

abstractmethod signal(sig=None, *, spid=1)

Return type:

None

abstractmethod cancel()

Return type:

None

abstractmethod wait(*, timeout=None)

Return type:

InstanceResult

abstractmethod run(command, *, shell=False, args=(), env=None, cwd=None, uid=None, gid=None, stdin=None, stdin_open=False, truncate_output_at=None)

Return type:

SubprocessContract

abstractmethod shutdown()

Return type:

None

class contree_sdk.session.contracts.AsyncOperationContract

An operation lifecycle. wait stores response before returning; cleanup preserves primary errors.

uuid: str

context: OperationContext | None

response: OperationResponse | None

abstractmethod async apply_files(files)

Return type:

None

add_observer(observer)

Register an observer before starting the shared operation reader.

A None event marks EOF, with an optional stream error. Observers must not consume events or wait for this operation. Implementations without this optional facility reject registration.

Return type:

None

abstractmethod events(*, since=None, spid=None, timeout=None)

Return type:

AsyncIterator[OperationEvent]

abstractmethod async status(*, inflight=False)

Return type:

OperationResponse

abstractmethod async send_stdin(data, *, spid=1, close=True)

Return type:

None

abstractmethod async pipe_stdin(chunks, *, spid=1, close=True, chunk_size=65536)

Return type:

StdinResult

abstractmethod async signal(sig=None, *, spid=1)

Return type:

None

abstractmethod async cancel()

Return type:

None

abstractmethod async wait(*, timeout=None)

Return type:

InstanceResult

abstractmethod async run(command, *, shell=False, args=(), env=None, cwd=None, uid=None, gid=None, stdin=None, stdin_open=False, truncate_output_at=None)

Return type:

AsyncSubprocessContract

abstractmethod async shutdown()

Return type:

None