client.proposals

client.proposals — the proposals operations.

On AsyncKindgi every method is the same, awaited.

client.proposals.list()

list(
    *,
    supervisor_id: str,
    limit: int | None = None,
    cursor: str | None = None,
    status: Literal['draft', 'dry-running', 'dry-run-passed', 'dry-run-failed', 'proposed-for-review', 'approved', 'rejected', 'applied', 'rolled-back', 'withdrawn'] | None = None,
    agent_id: str | None = None,
    tier: Literal['prompt', 'retrieval', 'tool-config'] | None = None,
    scope_kind: Literal['tenant', 'org', 'project'] | None = None,
    scope_id: str | None = None,
    inherit: bool | None = None,
    timeout: float | None = None,
) -> FixProposalCollectionPage

List supervisor fix proposals. GET /v1/proposals

Cursor-paginated list scoped to (tenantId, supervisorId). Filters: ?status=, ?agentId=, ?tier=. Sort order is binding-defined (typically createdAt desc, id desc).

client.proposals.draft()

draft(
    *,
    supervisor_id: str,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> FixProposal

Draft a fix proposal. POST /v1/proposals

Inserts a new proposal in draft state. Duplicate proposals (same (supervisor, fingerprint) non-terminal) short-circuit to the pre-existing row and mark the response with X-Proposal-Deduped: true.

client.proposals.get()

get(*, supervisor_id: str, timeout: float | None = None) -> FixProposal

Fetch a fix proposal. GET /v1/proposals/{proposalId}

client.proposals.dry_run()

dry_run(
    *,
    supervisor_id: str,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> DryRunProposalResult

Dry-run a proposal against an eval dataset. POST /v1/proposals/{proposalId}/dry-run

Runs the candidate agent against the caller-supplied dataset + criterion. Transitions the proposal to dry-run-passed or dry-run-failed. Legal only from draft or dry-run-failed.

client.proposals.submit_review()

submit_review(
    *,
    supervisor_id: str,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> SubmitReviewProposalResult

Submit a dry-run-passed proposal for HITL review. POST /v1/proposals/{proposalId}/submit-review

Enqueues a HITL approval and transitions the proposal to proposed-for-review. Legal only from dry-run-passed. Body is optional; defaults auto-derive the reviewer role (meta-fixes → senior).

client.proposals.apply()

apply(
    *,
    supervisor_id: str,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ApplyProposalResult

Apply an approved proposal. POST /v1/proposals/{proposalId}/apply

Materializes the proposed change into a new agent version, registers it in the agent registry, and transitions the proposal to applied. Legal only from approved.

client.proposals.rollback()

rollback(
    *,
    supervisor_id: str,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> RollbackProposalResult

Roll back an applied proposal. POST /v1/proposals/{proposalId}/rollback

Unregisters the applied version from the agent registry and transitions the proposal to rolled-back. Legal only from applied.

client.proposals.withdraw()

withdraw(
    *,
    supervisor_id: str,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> FixProposal

Withdraw a non-terminal proposal. POST /v1/proposals/{proposalId}/withdraw

Transitions the proposal to withdrawn. Legal from any non-terminal state (draft | dry-running | dry-run-passed | dry-run-failed | proposed-for-review). Terminal states surface as 409 proposal-invalid-state-transition.