adk_suspension (erlang_adk v0.7.0)
View SourceStructured suspension contracts for external operations and user auth.
Tools call long_running/2 or request_credential/2 from execute/2. Both use the Runner's existing durable, invocation-scoped continuation mechanism. Public metadata is JSON-safe; credentials remain in an adk_credential_store and only opaque references cross the event boundary.
Summary
Functions
Atomically replace a pending PKCE verifier with the provider-issued credential while retaining the same opaque flow reference. This is the callback boundary applications (including Phoenix controllers) call after exchanging the authorization code. The exact pending value is used as the compare-and-swap expectation, so two callbacks cannot both complete a flow. Neither the verifier nor provider credential is returned.
Create an S256 PKCE verifier in private credential storage. The verifier is never returned. The public result can be merged into the auth request shown to a client. The flow reference is not a bearer token; store lookup remains bound to Principal and Provider.
Suspend for an application-managed OAuth/OIDC interaction. Request is produced by prepare_pkce/5 plus the provider's public authorization URI and scopes. Context must be the Runner tool context; it is checked here so this helper cannot be used outside an authenticated session invocation.
Functions
-spec complete_pkce(module(), adk_credential_store:handle(), binary(), binary(), binary(), binary(), map()) -> {ok, adk_credential_store:credential_ref()} | {error, term()}.
Atomically replace a pending PKCE verifier with the provider-issued credential while retaining the same opaque flow reference. This is the callback boundary applications (including Phoenix controllers) call after exchanging the authorization code. The exact pending value is used as the compare-and-swap expectation, so two callbacks cannot both complete a flow. Neither the verifier nor provider credential is returned.
-spec prepare_pkce(module(), adk_credential_store:handle(), binary(), binary(), binary()) -> {ok, map()} | {error, term()}.
Create an S256 PKCE verifier in private credential storage. The verifier is never returned. The public result can be merged into the auth request shown to a client. The flow reference is not a bearer token; store lookup remains bound to Principal and Provider.
Suspend for an application-managed OAuth/OIDC interaction. Request is produced by prepare_pkce/5 plus the provider's public authorization URI and scopes. Context must be the Runner tool context; it is checked here so this helper cannot be used outside an authenticated session invocation.