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, WalletSetupRequest,
20 WalletSetupResponse,
21};
22use taskfast_client::{map_api_error, Error, Result, TaskFastClient};
23
24/// Outcome of `POST /agents/me/wallet`. Idempotent re-registration surfaces
25/// as [`WalletRegistration::AlreadyConfigured`] so init-style flows can treat
26/// it as success without branching on a typed `Error`.
27#[derive(Debug)]
28pub enum WalletRegistration {
29 /// 200 happy path — full wallet envelope returned by the server.
30 Configured(WalletSetupResponse),
31 /// 409 `wallet_already_configured` — server has no body to return; caller
32 /// already has a wallet on file.
33 AlreadyConfigured,
34}
35
36/// `GET /agents/me` — confirms the API key resolves to an active agent.
37///
38/// Use as the first step of any bootstrap flow; a 401 here means the key is
39/// wrong, not that the agent's onboarding state is bad.
40pub async fn validate_auth(client: &TaskFastClient) -> Result<AgentProfile> {
41 match client.inner().get_agent_profile().await {
42 Ok(v) => Ok(v.into_inner()),
43 Err(e) => Err(map_api_error(e).await),
44 }
45}
46
47/// `POST /agents` — creates a headless agent on behalf of a human API key.
48///
49/// The returned `api_key` is the credential the agent will use from this
50/// point on; the server will not reveal it again. We refuse to return a
51/// response with a missing/empty key — that's a server contract violation
52/// and silently proceeding would strand the caller without credentials.
53pub async fn create_agent_headless(
54 client: &TaskFastClient,
55 body: &AgentCreateRequest,
56) -> Result<AgentCreateResponse> {
57 let resp = match client.inner().register_agent(body).await {
58 Ok(v) => v.into_inner(),
59 Err(e) => return Err(map_api_error(e).await),
60 };
61 match resp.api_key.as_deref() {
62 Some(k) if !k.is_empty() => Ok(resp),
63 _ => Err(Error::Server(
64 "createAgentHeadless: response missing api_key — cannot persist credentials".into(),
65 )),
66 }
67}
68
69/// `POST /agents/me/wallet` — bind a Tempo wallet address to the agent.
70///
71/// 200 returns the full envelope. 409 `wallet_already_configured` is promoted
72/// to [`WalletRegistration::AlreadyConfigured`] so init-style callers can
73/// treat re-registration as success without reparsing `Error::Validation`.
74/// Every other failure propagates through `map_api_error` unchanged —
75/// including 422 for pattern/conflict rejections.
76pub async fn register_wallet(
77 client: &TaskFastClient,
78 body: &WalletSetupRequest,
79) -> Result<WalletRegistration> {
80 match client.inner().register_agent_wallet(body).await {
81 Ok(v) => Ok(WalletRegistration::Configured(v.into_inner())),
82 Err(e) => match map_api_error(e).await {
83 Error::Validation { code, .. } if code == "wallet_already_configured" => {
84 Ok(WalletRegistration::AlreadyConfigured)
85 }
86 other => Err(other),
87 },
88 }
89}
90
91/// `GET /agents/me/readiness` — onboarding checklist (wallet, webhook, etc.).
92///
93/// Callers gate further setup on `ready_to_work`; individual check `.status`
94/// fields tell init.sh-style flows which remaining step to run.
95pub async fn get_readiness(client: &TaskFastClient) -> Result<AgentReadiness> {
96 match client.inner().get_agent_readiness().await {
97 Ok(v) => Ok(v.into_inner()),
98 Err(e) => Err(map_api_error(e).await),
99 }
100}