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.

Returns:

Type	Description
dict[str, object]	Immutable resource values supplied for this invocation.

project_root property

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

Returns:

Type	Description
Path	Resolved root directory of the evaluated target.

app_data property

Orbit's per-user writable data directory.

Returns:

Type	Description
Path	Writable Orbit AppData directory.

workflow property

Return the workflow snapshot supplied by Orbit for this invocation.

Returns:

Type	Description
dict[str, object]	Immutable workflow metadata, or an empty mapping when unavailable.

build property

Return the build snapshot supplied by Orbit.

Returns:

Type	Description
dict[str, object]	Immutable build metadata, or an empty mapping when unavailable.

test_cases property

Return the fixed target test cases selected for this build.

Returns:

Type	Description
list[dict[str, object]]	Selected fixed test-case definitions.

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.

Returns:

Type	Description
dict[str, object]	Latest completed supervisor response, or an empty mapping when unavailable.

current_issue_assessment property

Return this iteration's first supervisor-assessed actionable issue.

The post-supervision agent phase uses this as its sole objective. A rejected issue is deliberately returned too, so the runner can record an explicit skip rather than treating absence as approval.

function(function_id)

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

Parameters:

Name	Type	Description	Default
function_id	str	Stable graph function identifier shown in retained run evidence.	required

Yields:

Type	Description
None	Control to the wrapped function body.

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.

Parameters:

Name	Type	Description	Default
name	str	Non-empty relative name for the runner-owned asset set.	required

Returns:

Type	Description
Path	Writable AppData directory isolated from the target repository.

load_state(name, default=None, *, scope='runner')

Load mutable runner- or build-scoped state from Orbit AppData.

State is separate from immutable run evidence. Use it only for bounded continuation data required by a later run, such as a persona's last observation or next check. State values must be JSON-safe.

Parameters:

Name	Type	Description	Default
name	str	Stable state name containing letters, numbers, underscores, or hyphens.	required
default	object	Value returned when no saved state exists.	None
scope	str	"runner" for runner-isolated state (the default), or "build" for state shared by every runner in this build.	'runner'

Returns:

Type	Description
object	The saved JSON value or default when the named state is absent.

save_state(name, value, *, scope='runner')

Atomically save mutable runner- or build-scoped state in Orbit AppData.

The value is not copied into run evidence. Emit a bounded summary with :meth:emit_result when a particular state transition needs auditing.

Parameters:

Name	Type	Description	Default
name	str	Stable state name containing letters, numbers, underscores, or hyphens.	required
value	object	JSON-safe value to retain for a later invocation of this build.	required
scope	str	"runner" for runner-isolated state (the default), or "build" for state shared by every runner in this build.	'runner'

Returns:

Type	Description
dict[str, object]	State name, update timestamp, and JSON byte size.

visual_node_inputs(node_id, bindings=None)

Return declared upstream values for one generated visual-runner node.

Parameters:

Name	Type	Description	Default
node_id	str	The generated graph-node identifier requesting inputs.	required
bindings	dict[str, tuple[str, str]] | None	Input names mapped to (source_node_id, output_port). Generated visual runners provide this mapping from their data edges, so unrelated node output is never exposed implicitly.	None

Returns:

Type	Description
dict[str, object]	A dictionary keyed by the node's declared input ports. Missing
dict[str, object]	upstream values are omitted, allowing a custom script to apply a
dict[str, object]	default explicitly.

publish_visual_node_outputs(node_id, values)

Persist JSON-safe outputs from one generated visual-runner node.

run_visual_node(kind, *, node_id, config, inputs)

Dispatch one SDK-owned visual operation through its registry.

Custom Script nodes intentionally remain generated Python. All curated operations use this dispatcher so their catalog metadata, validation, and runtime implementation have one SDK owner.

visual_should_run(condition, *, inputs)

Evaluate a blueprint's safe, declarative node condition.

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.

Returns:

Type	Description
str | None	Checked-out commit SHA, or None when no HEAD is available.

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.

Returns:

Type	Description
list[dict[str, object]]	Retained snapshot metadata ordered 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.

Parameters:

Name	Type	Description	Default
snapshot_id	str	Identifier returned by :meth:snapshot_repository.	required

Returns:

Type	Description
dict[str, object]	Restored snapshot metadata and restoration timestamp.

save_before_each_snapshot()

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

Returns:

Type	Description
dict[str, object]	Baseline snapshot metadata, reusing an existing baseline for this run.

save_first_after_each_snapshot()

Save the first completed iteration from an after_each handler.

Returns:

Type	Description
dict[str, object] | None	First-iteration snapshot metadata, or None after iteration one.

restore_before_each_snapshot()

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

Returns:

Type	Description
dict[str, object]	Restored baseline metadata.

record_commit_change(before)

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

Parameters:

Name	Type	Description	Default
before	str | None	Commit SHA observed before the runner action.	required

Returns:

Type	Description
dict[str, object] | None	Commit-range evidence when HEAD changed, otherwise None.

windows_path(value)

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

Parameters:

Name	Type	Description	Default
value	str | Path	Path below a WSL /mnt/<drive> mount.	required

Returns:

Type	Description
str	Equivalent Windows drive path.

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.

Parameters:

Name	Type	Description	Default
relative_path	str | Path	Target-repository-relative file path to update.	required
content	str | bytes	UTF-8 text or raw bytes to write.	required
encoding	str	Encoding used when content is text.	'utf-8'

Returns:

Type	Description
dict[str, object]	Change status, content hash, target path, and retained version metadata.

file_versions(relative_path)

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

Parameters:

Name	Type	Description	Default
relative_path	str | Path	Target-repository-relative file path.	required

Returns:

Type	Description
list[dict[str, object]]	Retained version metadata ordered 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.

Parameters:

Name	Type	Description	Default
relative_path	str | Path	Target-repository-relative file path to restore.	required
version_id	str	Retained version identifier to restore.	required

Returns:

Type	Description
dict[str, object]	Restored path, selected version ID, and metadata for the new rollback version.

proposal_decisions()

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

Returns:

Type	Description
list[dict[str, object]]	Proposal decision and application events ordered 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.

Parameters:

Name	Type	Description	Default
proposal	dict[str, object]	JSON-safe proposal payload being decided.	required
decision	Literal['accepted', 'rejected']	"accepted" or "rejected".	required
proposal_id	str | None	Optional stable external identifier for the proposal.	None
rationale	str	Optional human-readable decision reason.	''

Returns:

Type	Description
dict[str, object]	Whether an event was newly recorded and its decision record.

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.

Parameters:

Name	Type	Description	Default
proposal_ids	list[str]	Accepted proposal identifiers linked to the file update.	required
file_update	dict[str, object]	Metadata returned by :meth:update_file.	required

Returns:

Type	Description
list[dict[str, object]]	Newly recorded proposal-application events.

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

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

Parameters:

Name	Type	Description	Default
proposal	dict[str, object]	JSON-safe proposal payload to accept.	required
proposal_id	str | None	Optional stable external proposal identifier.	None
rationale	str	Optional human-readable acceptance reason.	''

Returns:

Type	Description
dict[str, object]	Whether an event was newly recorded and its decision record.

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

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

Parameters:

Name	Type	Description	Default
proposal	dict[str, object]	JSON-safe proposal payload to reject.	required
proposal_id	str | None	Optional stable external proposal identifier.	None
rationale	str	Optional human-readable rejection reason.	''

Returns:

Type	Description
dict[str, object]	Whether an event was newly recorded and its decision record.

require_test_case_ids(required_ids, *, label='required test case')

Require that the declared fixed cases include every requested ID.

Parameters:

Name	Type	Description	Default
required_ids	set[str] | list[str] | tuple[str, ...]	Stable test-case IDs that must be selected.	required
label	str	Singular description used in an actionable validation error.	'required test case'

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

Returns:

Type	Description
object	The requested resource value or default when it is absent.

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.

Parameters:

Name	Type	Description	Default
prompt	str	Target-AI input to send using the configured model profile.	required

Returns:

Type	Description
dict[str, str]	Profile name, resolved model name, and target-AI response text.

complete_model_json(prompt, *, description='model response')

Run one target-AI turn and require a JSON object response.

Use this when a runner's prompt explicitly contracts the model to emit structured data. The raw text remains available through :meth:complete_model for free-form model tasks.

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.

Parameters:

Name	Type	Description	Default
message	str	Human-readable lifecycle progress message.	required

Returns:

Type	Description
None	None. The message is written to runner output.

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

Returns:

Type	Description
None	None. The target log entry is attached to current-step evidence.

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.

Parameters:

Name	Type	Description	Default
values	dict[str, object]	JSON-safe evidence object to attach to the current step.	required

Returns:

Type	Description
None	None. The evidence is emitted to Orbit's runner protocol.

register_evaluation(feedback, *, subject='agent_change', changed_files=None, validation='', improvement_fingerprint='')

Register an AI-agent result that should receive a supervisor evaluation.

Register only after the agent has completed a meaningful change or produced actionable feedback. Merely running an iteration does not create an evaluation, score, or approval decision.

Parameters:

Name	Type	Description	Default
feedback	str	Concise account of the agent's completed work and its evidence.	required
subject	str	Stable evaluation subject. agent_change is the supported default for autonomous SDK agents.	'agent_change'
changed_files	list[str] | None	Repository-relative files changed by the agent, if any.	None
validation	str	Verification performed by the agent after its work.	''

Returns:

Type	Description
dict[str, object]	The structured evaluation request emitted for the current step.

run_ai_agent(prompt, *, provider, options='', timeout=1800)

Run a locally installed coding agent and retain its completion evidence.

The agent must print ORBIT_AGENT_FEEDBACK: <summary> as its final feedback line to opt its work into evaluation. This keeps a silent or no-op agent run from creating a score for the iteration.

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.

Parameters:

Name	Type	Description	Default
cases	list[dict[str, object]] | None	Optional fixed cases to run. The build's selected cases are used when omitted.	None

Returns:

Type	Description
dict[str, object]	Per-case pass/fail evidence, screenshots, page HTML, and artifact directory metadata.

exec(command, *, cwd=None, timeout=None, env=None, input=None, target_log_source=None, target_log_exclude_prefixes=(), merge_stderr=True)

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
input	str | None	Optional standard input sent to the child before its output is collected.	None
target_log_source	str | None	When set, forward bounded child-output lines to the target-log stream under this source name.	None
target_log_exclude_prefixes	tuple[str, ...]	Output prefixes retained for the caller but excluded from target logs, for structured child results.	()
merge_stderr	bool	When True (the default), include standard error in the returned output. Set to False when a child reserves standard output for a machine-readable response; standard error is still printed and forwarded to target logs.	True

Returns:

Type	Description
str	Standard output, plus standard error when merge_stderr is true.

Raises:

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

command_from_env(command_env)

Parse one externally configured command from the runner environment.

The value may be a shell-style command string or a JSON array of strings. The executable must be present; empty arguments remain valid because some tools use them intentionally.

run_command_action(*, command_env, action, timeout=None, env=None, log_source=None, log_exclude_prefixes=(), stdout_only=False)

Run one action of an externally configured command.

Parameters:

Name	Type	Description	Default
command_env	str	Environment variable holding the command configuration.	required
action	str	Final argument passed to the external command.	required
timeout	int | None	Maximum duration in seconds.	None
env	dict[str, str] | None	Additional environment values for the child command.	None
log_source	str | None	Optional target-log source for child output.	None
log_exclude_prefixes	tuple[str, ...]	Child-output prefixes excluded from target logs.	()
stdout_only	bool	Return only stdout, preserving stderr for logs. Use for commands whose stdout is a structured response.	False

parse_json_object(output, *, description='command output')

Parse and require exactly one JSON object from command output.

run_json_action(*, command_env, action, input_env, input_data, timeout=None, log_source=None)

Run one external action that returns a JSON object on standard output.

require_test_cases(*, label='fixed test case')

Require at least one declared fixed test case for a runner contract.

Runner registration

Runner

Register lifecycle handlers without owning runtime context operations.

__init__(graph_definition=None)

Create a runner registry, using the public graph singleton by default.

phase(name, *, step_id=None)

Register one handler for an Orbit lifecycle phase.

main()

Dispatch the lifecycle phase requested by the Orbit process.