Module adcp.task_options

Per-call execution options and deadline recovery metadata.

Functions

def mark_task_dispatched(client_token: object | None,
task_name: str,
*,
mutating: bool,
idempotency_key: str | None) ‑> None

Expand source code

def mark_task_dispatched(
    client_token: object | None,
    task_name: str,
    *,
    mutating: bool,
    idempotency_key: str | None,
) -> None:
    """Record that a protocol call may now have reached the seller."""

    state = _current_task_execution.get()
    if state is None or state.client_token is not client_token:
        return
    if state.deadline is not None and asyncio.get_running_loop().time() >= state.deadline:
        raise _TaskDeadlineExpiredError
    if mutating and idempotency_key is not None and state.mutation_recovery is None:
        state.mutation_recovery = TaskRecoveryMetadata(
            task_name=task_name,
            operation_id=state.operation_id,
            idempotency_key=idempotency_key,
        )

Record that a protocol call may now have reached the seller.

async def run_with_timeout(awaitable_factory: Callable[[], Awaitable[T]], timeout: float) ‑> ~T

Expand source code

async def run_with_timeout(awaitable_factory: Callable[[], Awaitable[T]], timeout: float) -> T:
    """Run under ``asyncio.wait_for`` without relabeling inner timeouts."""

    async def run() -> T:
        try:
            return await awaitable_factory()
        except _TIMEOUT_ERRORS as exc:
            raise _BodyTimeoutError(exc) from exc

    try:
        return await asyncio.wait_for(run(), timeout=timeout)
    except _BodyTimeoutError as exc:
        raise exc.cause from exc.cause.__cause__
    except _TIMEOUT_ERRORS as exc:
        raise _TaskDeadlineExpiredError from exc

Run under asyncio.wait_for without relabeling inner timeouts.

Classes

class TaskOptions (timeout: float | None = None)

Expand source code

@dataclass(frozen=True, slots=True)
class TaskOptions:
    """Options for one complete SDK task call.

    ``timeout`` is a non-resetting wall-clock budget in seconds. It covers the
    full client lifecycle: discovery, capability/version and signing preflight,
    protocol dispatch, response validation, and postflight projection. It does
    not replace the transport timeout configured on :class:`~adcp.AgentConfig`.

    A timeout of ``None`` disables the task-level deadline.
    """

    timeout: float | None = None

    def __post_init__(self) -> None:
        timeout = self.timeout
        if timeout is None:
            return
        if isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
            raise ValueError("timeout must be a finite positive number of seconds")

Options for one complete SDK task call.

timeout is a non-resetting wall-clock budget in seconds. It covers the full client lifecycle: discovery, capability/version and signing preflight, protocol dispatch, response validation, and postflight projection. It does not replace the transport timeout configured on :class:~adcp.AgentConfig.

A timeout of None disables the task-level deadline.

Instance variables

var timeout : float | None

Expand source code

@dataclass(frozen=True, slots=True)
class TaskOptions:
    """Options for one complete SDK task call.

    ``timeout`` is a non-resetting wall-clock budget in seconds. It covers the
    full client lifecycle: discovery, capability/version and signing preflight,
    protocol dispatch, response validation, and postflight projection. It does
    not replace the transport timeout configured on :class:`~adcp.AgentConfig`.

    A timeout of ``None`` disables the task-level deadline.
    """

    timeout: float | None = None

    def __post_init__(self) -> None:
        timeout = self.timeout
        if timeout is None:
            return
        if isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
            raise ValueError("timeout must be a finite positive number of seconds")

class TaskRecoveryMetadata (task_name: str,
operation_id: str,
idempotency_key: str,
outcome_unknown: bool = True)

Expand source code

@dataclass(frozen=True, slots=True)
class TaskRecoveryMetadata:
    """Safe retry identity for a timed-out mutating task.

    ``outcome_unknown`` is always true: once dispatch begins, a deadline cannot
    prove whether the seller committed the operation. Retry the exact original
    request with ``idempotency_key``; do not mint a new key.
    """

    task_name: str
    operation_id: str
    idempotency_key: str = field(repr=False)
    outcome_unknown: bool = True

Safe retry identity for a timed-out mutating task.

outcome_unknown is always true: once dispatch begins, a deadline cannot prove whether the seller committed the operation. Retry the exact original request with idempotency_key; do not mint a new key.

Instance variables

var idempotency_key : str

Expand source code

@dataclass(frozen=True, slots=True)
class TaskRecoveryMetadata:
    """Safe retry identity for a timed-out mutating task.

    ``outcome_unknown`` is always true: once dispatch begins, a deadline cannot
    prove whether the seller committed the operation. Retry the exact original
    request with ``idempotency_key``; do not mint a new key.
    """

    task_name: str
    operation_id: str
    idempotency_key: str = field(repr=False)
    outcome_unknown: bool = True

var operation_id : str

Expand source code

@dataclass(frozen=True, slots=True)
class TaskRecoveryMetadata:
    """Safe retry identity for a timed-out mutating task.

    ``outcome_unknown`` is always true: once dispatch begins, a deadline cannot
    prove whether the seller committed the operation. Retry the exact original
    request with ``idempotency_key``; do not mint a new key.
    """

    task_name: str
    operation_id: str
    idempotency_key: str = field(repr=False)
    outcome_unknown: bool = True

var outcome_unknown : bool

Expand source code

@dataclass(frozen=True, slots=True)
class TaskRecoveryMetadata:
    """Safe retry identity for a timed-out mutating task.

    ``outcome_unknown`` is always true: once dispatch begins, a deadline cannot
    prove whether the seller committed the operation. Retry the exact original
    request with ``idempotency_key``; do not mint a new key.
    """

    task_name: str
    operation_id: str
    idempotency_key: str = field(repr=False)
    outcome_unknown: bool = True

var task_name : str

Expand source code

@dataclass(frozen=True, slots=True)
class TaskRecoveryMetadata:
    """Safe retry identity for a timed-out mutating task.

    ``outcome_unknown`` is always true: once dispatch begins, a deadline cannot
    prove whether the seller committed the operation. Retry the exact original
    request with ``idempotency_key``; do not mint a new key.
    """

    task_name: str
    operation_id: str
    idempotency_key: str = field(repr=False)
    outcome_unknown: bool = True