API reference

This page is generated from backend/orbit_sdk.py at documentation build time.

Runner context

RunnerContext dataclass

Per-phase SDK interface supplied to a runner handler.

Do not construct this class in a normal runner. Decorate a function with @runner.phase(...) and Orbit creates the context when it invokes that phase. The context is scoped to one process invocation and one iteration.

Attributes:

Name	Type	Description
phase	str	The lifecycle phase currently being invoked.
target_repository	Path	Root directory of the evaluated target.
mode	str	Execution mode, normally "run" or "test".
loop_index	int	One-based evaluation iteration number.
environment	dict[str, str]	Environment snapshot passed to the runner process.

resources property

Return the immutable resource snapshot provided for this invocation.

The snapshot can contain the workflow, build, fixed test cases, model profile, and execution-environment settings. Prefer the typed convenience properties when one is available.

project_root property

Evaluation target root; use this instead of a machine-specific path.

app_data property

Orbit's per-user writable data directory.

workflow property

Return the workflow snapshot supplied by Orbit for this invocation.

build property

Return the build snapshot supplied by Orbit.

test_cases property

Return the fixed target test cases selected for this build.

previous_supervisor_feedback property

Return the latest completed supervisor response for this run.

Runner phases run in separate subprocesses. Reading the retained run record lets the next iteration use the previous iteration's feedback without coupling a runner to a target-specific state file.

function(function_id)

Record one graph-annotated function's outcome within this lifecycle phase.

project_path(*parts)

Resolve a target-repository path without allowing path traversal.

Parameters:

Name	Type	Description	Default
*parts	str	Relative path components inside :attr:project_root.	()

Returns:

Type	Description
Path	An absolute target-repository path.

Raises:

Type	Description
ValueError	If the path escapes the target repository.

managed_asset_dir(name)

Return a private, runner-managed AppData directory for a named asset set.

materialize_assets(name, files)

Atomically materialize runner-owned files outside the target repository.

Use this for temporary scripts, fixtures, or adapter configuration that belongs to the runner rather than the evaluated project. Orbit emits a manifest with content hashes as step evidence.

Parameters:

Name	Type	Description	Default
name	str	Stable relative name for this runner-managed asset set.	required
files	dict[str, str | bytes]	Relative paths and their UTF-8 text or byte content.	required

Returns:

Type	Description
dict[str, object]	The asset directory, manifest SHA-256, and hashes by file path.

write_artifact(relative_path, content, *, content_type='application/octet-stream')

Persist immutable run evidence in AppData and attach its metadata to the step.

Parameters:

Name	Type	Description	Default
relative_path	str | Path	Relative evidence path within the current run and iteration.	required
content	str | bytes	Text or bytes to retain.	required
content_type	str	MIME type used when the artifact is presented.	'application/octet-stream'

Returns:

Type	Description
dict[str, object]	Artifact path, SHA-256, size, content type, and relative path.

save_data_file(relative_path, content, *, label='', content_type='application/octet-stream')

Save a developer-named data file for the current evaluation iteration.

Call this from any lifecycle phase where the data becomes meaningful. The label is display metadata for the evaluation UI, not a filesystem name; it can describe why this file was retained. The UI exposes both the actual filename and the full AppData path for copying.

Parameters:

Name	Type	Description	Default
relative_path	str | Path	Relative file path within this run and iteration.	required
content	str | bytes	Text or bytes to retain.	required
label	str	Optional human-readable display name for this data file.	''
content_type	str	MIME type used when the file is presented.	'application/octet-stream'

Returns:

Type	Description
dict[str, object]	File metadata, including the label, actual filename, and path.

git_candidate(paths=None, *, retain_patch=False)

Summarize the current Git candidate without flooding runner output with its diff.

Parameters:

Name	Type	Description	Default
paths	list[str] | None	Optional target-relative paths to limit the Git diff.	None
retain_patch	bool	Store the binary diff as an artifact when it is non-empty.	False

Returns:

Type	Description
dict[str, object]	A candidate fingerprint, changed paths, and optionally patch metadata.

git_head()

Return the checked-out commit, or None when the target is not a Git repository.

snapshot_repository(label, *, once=False)

Store the complete target worktree as Git objects without creating a commit.

The snapshot includes tracked, staged, untracked, and ignored files, together with the original index tree and HEAD reference. Git's object database deduplicates unchanged file blobs; Orbit keeps a private ref only so these otherwise-uncommitted objects survive Git garbage collection. The ref is not a branch, tag, or commit-history entry.

Parameters:

Name	Type	Description	Default
label	str	Stable checkpoint name such as "baseline" or "iteration-1".	required
once	bool	Return the existing checkpoint with this label for the run, rather than recording another one.	False

Returns:

Type	Description
dict[str, object]	Immutable snapshot metadata, including its worktree tree hash.

repository_snapshots()

List retained repository snapshots, newest first.

restore_repository_snapshot(snapshot_id)

Restore a repository snapshot without checking out or creating a commit.

Restoring returns the target worktree, index, and HEAD reference to the recorded state. It also removes files created after the snapshot, including ignored and untracked files inside the target repository. Call this only while Orbit exclusively owns the target repository.

save_before_each_snapshot()

Save this run's baseline once from a before_each handler.

save_first_after_each_snapshot()

Save the first completed iteration from an after_each handler.

restore_before_each_snapshot()

Restore the baseline saved by :meth:save_before_each_snapshot in after_all.

record_commit_change(before)

Retain commit-range evidence when a runner phase advances the target HEAD.

windows_path(value)

Convert a WSL-mounted path to a Windows path for a Windows child process.

update_file(relative_path, content, *, encoding='utf-8')

Atomically update a project file, retaining its pre-update version.

Snapshots and their metadata live under Orbit AppData rather than the target repository. Each changed write retains the prior bytes together with the runner iteration, phase, run ID, timestamp, and SHA-256 hashes. Use :meth:file_versions to inspect retained versions and :meth:rollback_file to restore a selected one.

file_versions(relative_path)

List retained pre-update versions for a project file, newest first.

rollback_file(relative_path, version_id)

Restore the pre-update state retained by version_id.

Rolling back first snapshots the current file as a new version. This makes a rollback reversible: call this method again using that newly returned version ID to return to the state before the rollback.

proposal_decisions()

Return recorded accepted/rejected proposals for this target, newest first.

record_proposal_decision(proposal, decision, *, proposal_id=None, rationale='')

Persist an auditable accepted or rejected improvement proposal.

The ledger is stored in Orbit AppData, outside the target repository. Repeating the same decision for unchanged proposal content is idempotent, while a changed decision is appended as a new event. This produces a compact event stream for a future proposal-review UI.

record_proposal_application(proposal_ids, file_update)

Link accepted proposals to the prompt version they changed.

This is an append-only lifecycle event. It lets a review UI traverse from a decision to an exact prompt snapshot and its rollback version without mutating the original decision record.

accept_proposal(proposal, *, proposal_id=None, rationale='')

Record that a proposal was selected for this target's improvement history.

reject_proposal(proposal, *, proposal_id=None, rationale='')

Record that a proposal was not selected for this target's improvement history.

resource(name, default=None)

Read a named value from Orbit's immutable resource snapshot.

Parameters:

Name	Type	Description	Default
name	str	Resource name, such as "model_profile".	required
default	object	Value returned when the resource is absent.	None

complete_model(prompt)

Run one target-AI turn using the build's configured model profile.

The profile contains provider settings only; its credential remains in the configured environment variable and is never emitted as evidence.

log(message)

Write an Orbit runner-progress message to the workflow log.

This is for runner lifecycle and adapter progress. It is intentionally different from :meth:target_log, which records events emitted by the evaluated target and appears separately in the run's Logs tab.

target_log(message, *, level='info', source='', timestamp=None)

Attach one bounded log line produced by the evaluation target.

Target logs are kept separately from Orbit's runner and workflow output. Call this from an adapter after it has collected a relevant target-side event; it is not intended to mirror the runner's own stdout. Orbit adds the run ID, iteration, and lifecycle phase before retaining the entry.

Parameters:

Name	Type	Description	Default
message	str	Non-empty target event text. It is trimmed to 4,000 characters.	required
level	str	One of debug, info, warn, warning, or error.	'info'
source	str	Optional stable target-service name, trimmed to 256 characters.	''
timestamp	str | None	Optional ISO-8601 timestamp. UTC time is used when omitted.	None

Raises:

Type	Description
ValueError	If the message is empty, level is unsupported, or timestamp is not a string.

emit_result(values)

Attach JSON-safe structured evidence to the current Orbit step.

Use this for machine-consumed evidence such as scores, metrics, or proposal records. Values must be JSON serializable. Repeated result objects are merged by key, so prefer a single object for related data; use :meth:target_log for append-only target logging.

playwright_journey(cases=None)

Run bounded, read-only Playwright page checks for the supplied cases.

The browser process is short lived. Scheduling, locking, and any application-server lifecycle remain Orbit's responsibility.

exec(command, *, cwd=None, timeout=None, env=None)

Run one bounded child command and return its captured output.

A runner phase is deliberately not a scheduler. Returning the output lets a phase turn its one-shot result into Orbit-owned structured evidence without starting a persistent child daemon.

Parameters:

Name	Type	Description	Default
command	list[str]	Executable and arguments, passed without a shell.	required
cwd	Path | None	Child working directory; defaults to the target repository.	None
timeout	int | None	Maximum duration in seconds; no timeout when omitted.	None
env	dict[str, str] | None	Environment values that supplement the runner environment.	None

Returns:

Type	Description
str	Combined standard output and standard error from the child.

Raises:

Type	Description
TimeoutExpired	If the child exceeds timeout.
SystemExit	If the child exits with a non-zero status.

Runner registration

Runner

Register lifecycle handlers and dispatch the phase requested by Orbit.

phase(name)

Register a function as a handler for one runner lifecycle phase.

Parameters:

Name	Type	Description	Default
name	str	Lifecycle phase name, normally one of before_all, before_each, execute, verify, after_each, or after_all. Legacy names are accepted for compatibility.	required

Returns:

Type	Description
Callable[[Callable[[RunnerContext], None]], Callable[[RunnerContext], None]]	A decorator that leaves the registered handler unchanged.

main()

Dispatch the phase passed by Orbit and retain any commit-range evidence.

Place runner.main() behind an if __name__ == "__main__" guard in every runner asset. Orbit supplies the --phase argument and process environment; callers should not invoke this method directly.