The runtime supplies a policy-safe turn; the policy returns a proposal, no
action, or a lifecycle request. A proposal does not itself mutate the environment.
from ora.agent.contracts import (
PolicySession,
PolicySessionCapabilities,
PolicyTurnInput,
PolicyRuntimeEvent,
ActionProposal,
NoAction,
LifecycleRequest,
)
PolicySession
class PolicySession(Protocol)
| Attribute |
Type |
Default |
Description |
capabilities |
PolicySessionCapabilities |
|
|
start
start() -> None
act
act(turn: PolicyTurnInput) -> PolicyOutcome
accept_runtime_event
accept_runtime_event(event: PolicyRuntimeEvent) -> None
interrupt
interrupt(reason: str = 'operator_interrupt') -> None
close
close() -> None
PolicySessionCapabilities
class PolicySessionCapabilities
Backend facts used for orchestration, never policy coaching.
| Attribute |
Type |
Default |
Description |
runtime_kind |
Literal['scripted', 'managed_coder', 'native'] |
|
|
context_owner |
Literal['none', 'managed', 'harness'] |
|
|
tool_transport |
Literal['in_process', 'mcp', 'direct'] |
|
|
request_visibility |
Literal['none', 'project_exact', 'wire_exact'] |
|
|
supports_images |
bool |
|
|
supports_interrupt |
bool |
|
|
class PolicyTurnInput
Immutable, privilege-clean input for one observation-scoped policy turn.
| Attribute |
Type |
Default |
Description |
task_id |
str |
|
|
task_instruction |
str |
|
|
context |
Mapping[str, Any] |
|
|
image_path |
Path | None |
|
|
observation_id |
str | None |
|
|
observation_step |
int | None |
|
|
budget |
Mapping[str, Any] |
field(default_factory=dict) |
|
interaction_phase |
str |
'observation_ready' |
|
fresh_observation_required |
bool |
False |
|
allow_reminder |
bool |
True |
|
terminal_lifecycle |
bool |
False |
|
task_sha256 |
str |
'' |
|
image_paths |
tuple[Path, ...] |
() |
|
runtime_kwargs() -> dict[str, Any]
Project the typed turn into the runtime-owned invocation shape.
turn_budget is the round budget left when this turn starts. The
observation's context.remaining_budget was published with the
observation and goes stale when the Supervisor asks again on the same
observation, so a core caps its model calls by turn_budget.
PolicyRuntimeEvent
class PolicyRuntimeEvent
One trusted outer-loop fact delivered identically to every policy backend.
| Attribute |
Type |
Default |
Description |
kind |
Literal['fresh_observation', 'environment_receipt', 'action_discarded', 'official_verdict', 'run_termination', 'operator_message'] |
|
|
payload |
Mapping[str, Any] |
|
|
observation_id |
str | None |
None |
|
observation_step |
int | None |
None |
|
mutable_payload
mutable_payload() -> dict[str, Any]
ActionProposal
class ActionProposal
| Attribute |
Type |
Default |
Description |
action |
Mapping[str, Any] | None |
|
|
model_calls |
int |
|
|
details |
Mapping[str, Any] |
field(default_factory=dict) |
|
kind |
Literal['action'] |
'action' |
|
as_record
as_record() -> dict[str, Any]
NoAction
class NoAction
| Attribute |
Type |
Default |
Description |
reason |
str |
|
|
model_calls |
int |
|
|
details |
Mapping[str, Any] |
field(default_factory=dict) |
|
kind |
Literal['no_action'] |
'no_action' |
|
as_record
as_record() -> dict[str, Any]
LifecycleRequest
class LifecycleRequest
| Attribute |
Type |
Default |
Description |
reason |
str |
|
|
model_calls |
int |
|
|
details |
Mapping[str, Any] |
field(default_factory=dict) |
|
kind |
Literal['lifecycle'] |
'lifecycle' |
|
as_record
as_record() -> dict[str, Any]