Pause an Action for one accountable human decision

Three SDK calls, three different contracts

ctx.request_approval(...)

Ask the authenticated human to approve one fully described action. Success returns None.

ctx.request_input(...)

Collect exactly one text, selection, phone, or third-party secret value.

ctx.request_auth(...)

Ask Shimpz to prove an assurance class without exposing the factor to the Action.

The decorator is the reviewed capability boundary

from typing import TypedDict

from shimpz import Context, InputOption, InputRequest, action, text


class CreatedRecord(TypedDict):
    id: str
    status: str


@action(
    human_requests=["input:choice", "auth:password"],
    description="Create a DNS record in one of your zones.",
)
async def run(zone: str, *, ctx: Context) -> CreatedRecord:
    mode = ctx.request_input(
        InputRequest(
            kind="choice",
            title=text("Choose the DNS mode"),
            description=text("Select how this record should answer traffic."),
            label=text("Mode"),
            options=(
                InputOption("proxied", text("Proxied")),
                InputOption("dns-only", text("DNS only")),
            ),
        )
    )
    ctx.request_auth(
        "password",
        title=text("Confirm this DNS change"),
        description=text("Re-enter your Supervisor password to authorize this action."),
    )
    return await create_record(zone, mode)

Every exact kind must appear in @action(human_requests=[...]). An undeclared kind is rejected before a modal appears. Titles, descriptions, labels, placeholders, and options are bounded English shimpz.text messages that Team shows in each person's interface language; they never grant authority. These examples require SDK 0.7.1 and CLI 0.9.0 or newer. The provider operation at the end is an illustrative helper that the Creator implements.

Success resumes; every other outcome stops

• Approval, valid input, or successful assurance resumes the logical Action.
• Denial, modal dismissal, cancellation, expiry, invalid authentication, or unavailable assurance stops it.
• A blocked request never returns control to Assistant code and is never retried automatically.
• One Action may request at most 8 decisions; one Team turn may request at most 16.
• Each displayed challenge expires after 300 seconds.