Write a replay-safe prefix and an action-only suffix

One logical Action may use several short processes

1. The Controller invokes the reviewed Action with its original input and no response transcript.
2. The SDK reaches request ordinal 0, emits a canonical suspension, and terminates the process.
3. Team validates the declared capability and exposes the challenge in Local Admin.
4. The authenticated Supervisor responds once before the 300-second expiry.
5. Team re-invokes the exact immutable binding with the original input and a bounded response transcript.
6. The SDK matches kind, ordinal, and request fingerprint, returns the recorded value, and continues.
7. A later request repeats the cycle; a terminal result is accepted only after every response was consumed.

Collect inputs, request one authorization, then access secrets and act

from typing import TypedDict

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


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


@action(
    integrations=["cloudflare"],
    human_requests=["input:choice", "auth:password"],
    description="Publish a DNS record in one of your Cloudflare zones.",
)
async def run(zone: str, *, ctx: Context) -> PublishedRecord:
    # Replay-safe prefix: pure decisions only.
    mode = ctx.request_input(
        InputRequest(
            kind="choice",
            title=text("Choose the DNS mode"),
            description=text("Select exactly one routing behavior."),
            label=text("Mode"),
            options=(
                InputOption("proxied", text("Proxied")),
                InputOption("dns-only", text("DNS only")),
            ),
        )
    )
    ctx.request_auth(
        "password",
        title=text("Confirm the DNS publication"),
        description=text("Reauthenticate before this external write."),
    )

    # Provider phase: Team adds the Integration bearer, and no human request may follow.
    return await publish_record(ctx, zone, mode)

The first ctx.fetch call closes the human-request phase: the SDK rejects every later request, and Team refuses one, so a replay never repeats a provider call. An Action that declares an authorization request may call a provider only after that request is answered. The final provider helper is illustrative Creator code.

The same ordinal must describe the same request on every replay

• Build request copy and options from original Action inputs or already replayed responses.
• Do not use current time, randomness, unordered external data, mutable globals, or network reads.
• Keep option values stable; changing a message, a parameter value, bounds, order, or kind changes the canonical fingerprint. The display language never changes it, because copy travels as catalog references.
• A changed Assistant image, Integration generation, Team context, principal, or fingerprint fails closed.

Denial is control flow owned by Team, not an exception to recover from

Denial, dismiss, cancellation, expiry, failed authentication, unavailable assurance, malformed frames, and divergent replay all stop the logical Action. Assistant code does not receive a false value or catchable denial result. Team deletes the abandoned continuation and never retries the action automatically.

If an earlier Action in the same Brain-requested batch already completed an external action, that action remains complete. The blocked batch is abandoned and audited; a later user turn is a separate operation.

Keep every sensitive value at its narrowest authority

Integration token

Never enters the Assistant: Team adds it to a declaring Action's calls to the provider's API hosts.

input:password

Always a declared Stored Input that Team keeps encrypted for that Team and places in the declaring Action's calls to its host; the Action never receives it. Prefer an OAuth Integration whenever possible.

request_auth factor

Verified by Admin and Team. It never enters Assistant input, transcript, logs, or results.

Public request metadata

Catalog references for the title, description, labels, and options, their typed parameter values, Assistant identity, Action identity, and expiry only. Parameter values are never sent to the translator.

Design within the closed budget

• At most 8 human requests in one logical Action.
• At most 16 human requests across one Team turn.
• Each challenge expires 300 seconds after Team creates it.
• Password input must be the last request across the entire Team turn and is never durably resumed.
• Local can restore only a non-secret paused request after a controller restart.