cayu.approvals.user_input

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`PendingUserInput`

from cayu.approvals import PendingUserInput

Durable checkpoint state for a session paused on an ask_user question.

max_steps, limits, budget_limits, and retry_policy persist the original run’s configuration across the pause so resolving the question resumes with the same config instead of fresh defaults. A resolution request may restate those values only when they preserve the invocation’s frozen execution profile. Older pauses without exact authority migrate to a separate ambiguous tombstone and never instantiate this executable model.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`schema_version`	`Literal[1]`	`1`
`session_id`	`str`	`required`
`session_instance_id`	`str`	`required`
`source_interaction_id`	`str`	`required`
`source_run_epoch`	`StrictInt`	`Field(ge=0, le=MAX_DURABLE_JSON_INTEGER)`
`input_id`	`str`	`required`
`tool_round_id`	`str`	`required`
`model_step_id`	`str`	`required`
`model_attempt_id`	`str`	`required`
`model_step`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_DURABLE_JSON_INTEGER)`
`tool_call_id`	`str`	`required`
`tool_name`	`str`	`required`
`question`	`str`	`required`
`options`	`list[str]`	`Field(default_factory=list)`
`arguments`	`dict[str, Any]`	`Field(default_factory=dict)`
`agent_name`	`str`	`required`
`environment_name`	`str \| None`	`None`
`workspace_id`	`str \| None`	`None`
`task_id`	`str \| None`	`None`
`interaction_id`	`str \| None`	`None`
`execution_profile_fingerprint`	`str`	`Field(min_length=64, max_length=64, pattern='^[0-9a-f]{64}$')`
`tool_exposure`	`ResolvedToolExposureAuthority \| None`	`None`
`tool_calls`	`list[PendingToolCallApproval]`	`required`
`assistant_message_state`	`Literal['published', 'quarantined']`	`'published'`
`quarantined_assistant_message`	`Message \| None`	`None`
`assistant_publication`	`AssistantToolRoundPublication \| None`	`None`
`staged_terminals`	`list[StagedToolCallTerminal]`	`Field(default_factory=list)`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`run_limit_accounting`	`RunLimitAccountingContext \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`

validate_nonblank_fields (method)

PendingUserInput.validate_nonblank_fields(value: str, info) -> str

validate_tool_round_identity (method)

PendingUserInput.validate_tool_round_identity() -> PendingUserInput

copy_tool_exposure (method)

PendingUserInput.copy_tool_exposure(value: ResolvedToolExposureAuthority | None) -> ResolvedToolExposureAuthority | None

validate_question (method)

PendingUserInput.validate_question(value: str, info) -> str

validate_optional_nonblank_fields (method)

PendingUserInput.validate_optional_nonblank_fields(value: str | None, info) -> str | None

validate_options (method)

PendingUserInput.validate_options(value: list[str], info) -> list[str]

copy_arguments (method)

PendingUserInput.copy_arguments(value: dict[str, Any], info) -> dict[str, Any]

copy_structured_output (method)

PendingUserInput.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_tool_calls (method)

PendingUserInput.copy_tool_calls(value: list[PendingToolCallApproval]) -> list[PendingToolCallApproval]

copy_quarantined_assistant_message (method)

PendingUserInput.copy_quarantined_assistant_message(value: Message | None) -> Message | None

copy_assistant_publication (method)

PendingUserInput.copy_assistant_publication(value: AssistantToolRoundPublication | None) -> AssistantToolRoundPublication | None

copy_staged_terminals (method)

PendingUserInput.copy_staged_terminals(value: list[StagedToolCallTerminal]) -> list[StagedToolCallTerminal]

copy_limits (method)

PendingUserInput.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

PendingUserInput.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_retry (method)

PendingUserInput.copy_retry(value: RetryPolicy | None) -> RetryPolicy | None

Release source · Runtime guarantees · Capability guides

`UserInputRecoveryRequest`

from cayu.approvals import UserInputRecoveryRequest

Caller-supplied terminal outcome for a paused round’s tool with an unknown result.

Used when resolve_user_input reports manual_recovery_required: a tool in the paused round started on a prior resume but recorded no terminal event (a crash mid-tool), so it cannot be re-run automatically. The caller supplies the externally verified outcome for that tool_call_id; answer is re-supplied so the ask_user result is available if it was not already recorded before the crash.

max_steps, limits, budget_limits, and retry_policy default to None = “inherit the original run’s configuration” from the pending checkpoint.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`review_reference`	`HumanReviewReference \| None`	`Field(default=None, repr=False, exclude_if=lambda value: value is None)`
`answer_review_reference`	`HumanReviewReference \| None`	`Field(default=None, repr=False, exclude_if=lambda value: value is None)`
`session_id`	`str`	`required`
`task_worker_id`	`str \| None`	`None`
`task_handoff_id`	`str \| None`	`None`
`input_id`	`str`	`required`
`answer`	`str`	`required`
`tool_call_id`	`str`	`required`
`outcome`	`ToolApprovalRecoveryOutcome`	`required`
`message`	`str`	`required`
`structured`	`dict[str, Any] \| None`	`None`
`artifacts`	`list[dict[str, Any]]`	`Field(default_factory=list)`
`reason`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`resolved_by`	`ResolutionActor \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`loop_policies`	`SkipJsonSchema[tuple[LoopPolicy, ...]]`	`Field(default_factory=tuple, exclude=True)`

validate_nonblank_ids (method)

UserInputRecoveryRequest.validate_nonblank_ids(value: str, info) -> str

validate_task_worker_id (method)

UserInputRecoveryRequest.validate_task_worker_id(value: str | None) -> str | None

validate_task_handoff_authority (method)

UserInputRecoveryRequest.validate_task_handoff_authority() -> UserInputRecoveryRequest

copy_resolved_by (method)

UserInputRecoveryRequest.copy_resolved_by(value: ResolutionActor | None) -> ResolutionActor | None

validate_nonblank_text (method)

UserInputRecoveryRequest.validate_nonblank_text(value: str, info) -> str

validate_optional_reason (method)

UserInputRecoveryRequest.validate_optional_reason(value: str | None, info) -> str | None

copy_json_fields (method)

UserInputRecoveryRequest.copy_json_fields(value, info)

copy_structured_output (method)

UserInputRecoveryRequest.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_limits (method)

UserInputRecoveryRequest.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

UserInputRecoveryRequest.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_loop_policies (method)

UserInputRecoveryRequest.copy_loop_policies(value) -> tuple[LoopPolicy, ...]

Release source · Runtime guarantees · Capability guides

`UserInputResponse`

from cayu.approvals import UserInputResponse

Caller-supplied answer that resumes a session paused by ask_user.

max_steps, limits, budget_limits, and retry_policy default to None, which means “inherit the original run’s configuration” as persisted on the pending user-input checkpoint. An explicit value is accepted only when it preserves the invocation’s frozen execution profile.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`review_reference`	`HumanReviewReference \| None`	`Field(default=None, repr=False, exclude_if=lambda value: value is None)`
`session_id`	`str`	`required`
`task_worker_id`	`str \| None`	`None`
`task_handoff_id`	`str \| None`	`None`
`input_id`	`str`	`required`
`answer`	`str`	`required`
`structured`	`dict[str, Any] \| None`	`None`
`artifacts`	`list[dict[str, Any]]`	`Field(default_factory=list)`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`
`resolved_by`	`ResolutionActor \| None`	`None`
`max_steps`	`StrictInt \| None`	`Field(default=None, ge=1, le=MAX_STEPS)`
`limits`	`RunLimits \| None`	`None`
`budget_limits`	`tuple[BudgetLimit, ...] \| None`	`None`
`retry_policy`	`RetryPolicy \| None`	`None`
`structured_output`	`StructuredOutputSpec \| None`	`None`
`thinking`	`ThinkingConfig \| None`	`None`
`loop_policies`	`SkipJsonSchema[tuple[LoopPolicy, ...]]`	`Field(default_factory=tuple, exclude=True)`

validate_nonblank_ids (method)

UserInputResponse.validate_nonblank_ids(value: str, info) -> str

validate_task_worker_id (method)

UserInputResponse.validate_task_worker_id(value: str | None) -> str | None

validate_task_handoff_authority (method)

UserInputResponse.validate_task_handoff_authority() -> UserInputResponse

validate_answer (method)

UserInputResponse.validate_answer(value: str, info) -> str

copy_json_fields (method)

UserInputResponse.copy_json_fields(value, info)

copy_resolved_by (method)

UserInputResponse.copy_resolved_by(value: ResolutionActor | None) -> ResolutionActor | None

copy_structured_output (method)

UserInputResponse.copy_structured_output(value: StructuredOutputSpec | None) -> StructuredOutputSpec | None

copy_limits (method)

UserInputResponse.copy_limits(value: RunLimits | None) -> RunLimits | None

copy_budget_limits (method)

UserInputResponse.copy_budget_limits(value) -> tuple[BudgetLimit, ...] | None

copy_loop_policies (method)

UserInputResponse.copy_loop_policies(value) -> tuple[LoopPolicy, ...]

Release source · Runtime guarantees · Capability guides