Skip to main content
Version: 0.15 (latest)

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