cubeloop.session

ExecutionEventEnvelope

class

ExecutionEventEnvelope(run_id: str, attempt_id: str, seq: int, event: SessionEvent)

source

Attributes

• run_id: str
• attempt_id: str
• seq: int
• event: SessionEvent

ExecutionFinished

class

ExecutionFinished(
    result: ExecutionResult,
    type: Literal['execution_finished'] = 'execution_finished',
)

source

Attributes

• result: ExecutionResult
• type: Literal['execution_finished']

InputCommitted

class

InputCommitted(
    input_id: str,
    durability: InputDurability,
    type: Literal['input_committed'] = 'input_committed',
)

source

Attributes

• input_id: str
• durability: InputDurability
• type: Literal['input_committed']

SessionEvent

attribute

SessionEvent: TypeAlias = AgentEvent | InputCommitted | ExecutionFinished

source

InputEnvelope

class

InputEnvelope(input_id: str, message: Message, mode: InputMode)

source

Attributes

• input_id: str
• message: Message
• mode: InputMode

InputReceipt

class

InputReceipt(
    input_id: str,
    status: InputStatus,
    durability: InputDurability | None = None,
)

source

Attributes

• input_id: str
• status: InputStatus
• durability: InputDurability | None

ExecutionSession

class

ExecutionSession(agent: Agent)

Public lifecycle for sequential execution attempts owned by one Agent.

source

Attributes

• active_attempt_id: str | None
• turn_contexts: tuple[TurnExecutionContext, ...]
• state_context: JsonObject — The stable, live mapping persisted as checkpoint extra state.

Methods

load_checkpoint

load_checkpoint() -> CheckpointData | None

Atomically install checkpoint messages and extra while idle.

source

request_cancel

request_cancel() -> None

source

wait_for_idle

wait_for_idle() -> None

source

request_detach

request_detach() -> None

source

subscribe

subscribe(
    listener: Callable[[ExecutionEventEnvelope], Any],
    *,
    required: bool = False,
    name: str | None = None,
    capacity: int = 256,
    delivery_timeout: float = 1.0,
) -> Callable[[], None]

source

submit_input

submit_input(envelope: InputEnvelope) -> InputReceipt

source

cancel_input

cancel_input(input_id: str) -> InputReceipt

source

execute

execute(request: ExecutionRequest) -> ExecutionResult

Execute one attempt and return settled lifecycle facts.

source

ContinueExecutionRequest

class

ContinueExecutionRequest(
    run_id: str,
    attempt_id: str,
    kind: Literal['continue'] = 'continue',
)

source

Attributes

• run_id: str
• attempt_id: str
• kind: Literal['continue']

DeliveryError

class

DeliveryError(
    consumer: str,
    seq: int,
    reason: Literal['timeout', 'closed', 'error'],
    message: str = '',
)

source

Attributes

• consumer: str
• seq: int
• reason: Literal['timeout', 'closed', 'error']
• message: str

ExecutionBusy

class

Raised when an Agent already has an executing or finalizing attempt.

source

ExecutionError

class

ExecutionError(
    kind: Literal['cancelled', 'execution', 'finalization', 'inconsistent'],
    message: str,
    cause: BaseException | None = None,
)

source

Attributes

• kind: Literal['cancelled', 'execution', 'finalization', 'inconsistent']
• message: str
• cause: BaseException | None

ExecutionOutcome

attribute

ExecutionOutcome: TypeAlias = Literal['completed', 'suspended', 'cancelled', 'failed', 'incomplete']

source

ExecutionRequest

attribute

ExecutionRequest: TypeAlias = PromptExecutionRequest | RespondExecutionRequest | ContinueExecutionRequest

source

ExecutionResult

class

ExecutionResult(
    run_id: str,
    attempt_id: str,
    outcome: ExecutionOutcome,
    pending_request: HitlRequest | None = None,
    error: ExecutionError | None = None,
    checkpoint_committed: bool = False,
    history_consistent: bool = True,
    delivery_errors: tuple[DeliveryError, ...] = (),
)

source

Attributes

• run_id: str
• attempt_id: str
• outcome: ExecutionOutcome
• pending_request: HitlRequest | None
• error: ExecutionError | None
• checkpoint_committed: bool
• history_consistent: bool
• delivery_errors: tuple[DeliveryError, ...]

PromptExecutionRequest

class

PromptExecutionRequest(
    run_id: str,
    attempt_id: str,
    message: str | Message | list[Message],
    kind: Literal['prompt'] = 'prompt',
)

source

Attributes

• run_id: str
• attempt_id: str
• message: str | Message | list[Message]
• kind: Literal['prompt']

RespondExecutionRequest

class

RespondExecutionRequest(
    run_id: str,
    attempt_id: str,
    answer: StructuredValue,
    question_id: str | None = None,
    kind: Literal['respond'] = 'respond',
)

source

Attributes

• run_id: str
• attempt_id: str
• answer: StructuredValue
• question_id: str | None
• kind: Literal['respond']

MessageView

class

MessageView(
    role: str,
    content: tuple[FrozenObject, ...],
    metadata: Mapping[str, Any],
    run_id: str | None,
    _values: Mapping[str, Any],
)

source

Attributes

• role: str
• content: tuple[FrozenObject, ...]
• metadata: Mapping[str, Any]
• run_id: str | None

Methods

capture

capture(cls, message: Message) -> MessageView

source

ToolExecutionBinding

class

ToolExecutionBinding(
    name: str,
    definition: FrozenObject,
    parameters: type[BaseModel],
    execute: Callable[..., Awaitable[AgentToolResult]],
    hitl_builtin: bool,
    execution_mode: Literal['sequential', 'parallel'] | None,
    _source_id: int,
)

source

Attributes

• name: str
• definition: FrozenObject
• parameters: type[BaseModel]
• execute: Callable[..., Awaitable[AgentToolResult]]
• hitl_builtin: bool
• execution_mode: Literal['sequential', 'parallel'] | None

Methods

capture

capture(cls, tool: AgentTool) -> ToolExecutionBinding

source

TurnExecutionContext

class

TurnExecutionContext(
    turn_id: str,
    run_id: str,
    attempt_id: str,
    model: FrozenObject,
    reasoning: FrozenObject,
    system_prompt: str,
    messages: tuple[MessageView, ...],
    tools: tuple[ToolExecutionBinding, ...],
    policy_revision: str | None = None,
    model_attempt_id: str | None = None,
)

source

Attributes

• turn_id: str
• run_id: str
• attempt_id: str
• model: FrozenObject
• reasoning: FrozenObject
• system_prompt: str
• messages: tuple[MessageView, ...]
• tools: tuple[ToolExecutionBinding, ...]
• policy_revision: str | None
• model_attempt_id: str | None

Methods

capture

capture(
    cls,
    *,
    turn_id: str,
    run_id: str,
    attempt_id: str,
    model: Model,
    reasoning: ReasoningControl,
    system_prompt: str,
    messages: list[Message],
    tools: list[AgentTool] | None,
    policy_revision: str | None = None,
    model_attempt_id: str | None = None,
) -> TurnExecutionContext

source

matches_model

matches_model(model: Model, model_attempt_id: str | None) -> bool

source

binding_for

binding_for(name: str) -> ToolExecutionBinding | None

source

extend

extend(tool: AgentTool) -> TurnExecutionContext

source