taskfast_agent/bootstrap.rs
1// SPDX-License-Identifier: MIT
2//! Agent onboarding: auth validation, headless creation, readiness gate.
3//!
4//! Mirrors the legacy `packages/agent/src/bootstrap.ts` shape (pre-Rust
5//! rewrite) against the typed [`TaskFastClient`]. Three async entry points
6//! drive `scripts/init.sh` steps 2-4 + 9:
7//!
8//! - [`validate_auth`] — step 3, asserts the API key is valid.
9//! - [`create_agent_headless`] — step 2 BYOK-absent branch, returns the
10//! freshly-minted `api_key` (caller must persist; it never comes back).
11//! - [`get_readiness`] — steps 4 + 9, checks the onboarding gate is open.
12//!
13//! All three surface [`taskfast_client::Error`]. The create path adds one
14//! invariant the generated client cannot enforce: the server *must* return
15//! an `api_key`. If it doesn't, we fail loud rather than silently drop the
16//! only credential the caller will ever see.
17
18use taskfast_client::api::types::{
19 AgentCreateRequest, AgentCreateResponse, AgentProfile, AgentReadiness,
20};
21use taskfast_client::{map_api_error, Error, Result, TaskFastClient};
22
23/// `GET /agents/me` — confirms the API key resolves to an active agent.
24///
25/// Use as the first step of any bootstrap flow; a 401 here means the key is
26/// wrong, not that the agent's onboarding state is bad.
27pub async fn validate_auth(client: &TaskFastClient) -> Result<AgentProfile> {
28 match client.inner().get_agent_profile().await {
29 Ok(v) => Ok(v.into_inner()),
30 Err(e) => Err(map_api_error(e).await),
31 }
32}
33
34/// `POST /agents` — creates a headless agent on behalf of a human API key.
35///
36/// The returned `api_key` is the credential the agent will use from this
37/// point on; the server will not reveal it again. We refuse to return a
38/// response with a missing/empty key — that's a server contract violation
39/// and silently proceeding would strand the caller without credentials.
40pub async fn create_agent_headless(
41 client: &TaskFastClient,
42 body: &AgentCreateRequest,
43) -> Result<AgentCreateResponse> {
44 let resp = match client.inner().register_agent(body).await {
45 Ok(v) => v.into_inner(),
46 Err(e) => return Err(map_api_error(e).await),
47 };
48 match resp.api_key.as_deref() {
49 Some(k) if !k.is_empty() => Ok(resp),
50 _ => Err(Error::Server(
51 "createAgentHeadless: response missing api_key — cannot persist credentials".into(),
52 )),
53 }
54}
55
56/// `GET /agents/me/readiness` — onboarding checklist (wallet, webhook, etc.).
57///
58/// Callers gate further setup on `ready_to_work`; individual check `.status`
59/// fields tell init.sh-style flows which remaining step to run.
60pub async fn get_readiness(client: &TaskFastClient) -> Result<AgentReadiness> {
61 match client.inner().get_agent_readiness().await {
62 Ok(v) => Ok(v.into_inner()),
63 Err(e) => Err(map_api_error(e).await),
64 }
65}
66
67pub use crate::wallet::WalletRegistration;
68
69/// `POST /agents/me/wallet` — bind a Tempo wallet address to the agent.
70///
71/// Deprecated: use [`crate::wallet::register_wallet`] directly.
72#[deprecated(note = "use taskfast_agent::wallet::register_wallet")]
73pub async fn register_wallet(
74 client: &TaskFastClient,
75 body: &taskfast_client::api::types::WalletSetupRequest,
76) -> Result<WalletRegistration> {
77 crate::wallet::register_wallet(client, body.tempo_wallet_address.as_str()).await
78}