Skip to main content

firstpass_proxy/
kiosk.rs

1//! `firstpass kiosk` — one command, no questions, no prior state, always ends in a receipt.
2//!
3//! `onboard` asks three questions and wires your shell; `demo` proves the loop with no keys at
4//! all. The kiosk is the single-press button between them: look at the environment, pick the
5//! provider whose key is already there, write a config, stand the real proxy up, put one real
6//! request through it, and print the audit receipt. No prompts, so it behaves identically for a
7//! human at a terminal and for an agent with no tty — which is the point, since an agent that
8//! blocks on a question has failed to onboard.
9//!
10//! **It never dead-ends.** With no provider key, it does not print instructions and quit; it falls
11//! through to [`crate::demo`], whose local upstream needs no key, so pressing the button always
12//! produces a working, inspectable receipt. "Nothing happened, here is what to install" is the
13//! failure mode a kiosk exists to avoid.
14//!
15//! Config generation is [`crate::onboard::render_config`], not a second template. This repo has
16//! already paid for two implementations of the same config drifting apart.
17
18use crate::onboard::{LadderChoice, Provider, Shape, render_config};
19use firstpass_core::{GENESIS_HASH, Mode, Trace, verify_chain};
20use serde_json::{Value, json};
21use std::path::{Path, PathBuf};
22use std::sync::Arc;
23
24/// Anything that can go wrong. The kiosk reports plainly rather than panicking — it is the same
25/// binary operators run in production.
26type Fail = Box<dyn std::error::Error>;
27
28/// The provider the kiosk will open its ladder on, and the env var its key came from.
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub struct Pick {
31    /// Which provider.
32    pub provider: Provider,
33    /// The environment variable the key was found in.
34    pub key_env: &'static str,
35}
36
37/// Every provider the kiosk can start from, in priority order, with the key it needs.
38const CANDIDATES: [(Provider, &str); 3] = [
39    (Provider::Anthropic, "ANTHROPIC_API_KEY"),
40    (Provider::OpenAi, "OPENAI_API_KEY"),
41    (Provider::Google, "GEMINI_API_KEY"),
42];
43
44/// Pick the first provider whose key is present and non-blank. `None` means no key at all, which
45/// is a supported state, not an error — the caller falls through to the keyless demo.
46///
47/// A blank value counts as absent: `export ANTHROPIC_API_KEY=` in a stale shell profile is common,
48/// and treating it as present would route the kiosk into a guaranteed 401.
49pub fn pick_provider(env: impl Fn(&str) -> Option<String>) -> Option<Pick> {
50    CANDIDATES.iter().find_map(|&(provider, key_env)| {
51        env(key_env)
52            .filter(|v| !v.trim().is_empty())
53            .map(|_| Pick { provider, key_env })
54    })
55}
56
57/// The config the kiosk runs: the picked provider's ladder, JSON-shaped so a real gate does real
58/// work, in enforce mode so the receipt shows an actual routing decision rather than a passthrough.
59#[must_use]
60pub fn kiosk_config(pick: Pick) -> String {
61    render_config(&LadderChoice {
62        provider: pick.provider,
63        shape: Shape::Json,
64        mode: Mode::Enforce,
65    })
66}
67
68/// Print the audit receipt for one trace: every rung tried, what the gate said, what it cost, and
69/// what it saved against always calling the top of the ladder.
70pub fn print_receipt(trace: &Trace) {
71    println!("\x1b[1m── audit receipt ──────────────────────────────────\x1b[0m");
72    for a in &trace.attempts {
73        let verdict = match a.verdict {
74            firstpass_core::Verdict::Pass => "\x1b[32mPASS\x1b[0m",
75            firstpass_core::Verdict::Fail => "\x1b[31mFAIL\x1b[0m",
76            firstpass_core::Verdict::Abstain => "\x1b[33mABSTAIN\x1b[0m",
77        };
78        println!(
79            "  rung {} · {:<28} · {verdict} · ${:.4}",
80            a.rung, a.model, a.cost_usd
81        );
82    }
83    let f = &trace.final_;
84    println!("  ─────────────────────────────────────────────────");
85    println!("  total     ${:.4}", f.total_cost_usd);
86    println!(
87        "  baseline  ${:.4}   (always top-tier)",
88        f.counterfactual_baseline_usd
89    );
90    let pct = if f.counterfactual_baseline_usd > 0.0 {
91        f.savings_usd / f.counterfactual_baseline_usd * 100.0
92    } else {
93        0.0
94    };
95    println!(
96        "  \x1b[32mSAVED     ${:.4}   ({pct:.0}% cheaper at proven quality)\x1b[0m",
97        f.savings_usd
98    );
99    println!("  trace_id  {}", trace.trace_id);
100    println!(
101        "  chain     {}\n",
102        if verify_chain(std::slice::from_ref(trace), &trace.prev_hash).is_ok() {
103            "verified ✓"
104        } else {
105            "BROKEN"
106        }
107    );
108}
109
110/// Run the kiosk end to end.
111///
112/// # Errors
113/// A real provider call failed, the proxy could not bind, or no receipt was recorded. A *missing
114/// key* is not an error — it routes to the keyless demo.
115pub async fn run() -> Result<(), Fail> {
116    let Some(pick) = pick_provider(|k| std::env::var(k).ok()) else {
117        println!("\n\x1b[1mFirstpass kiosk\x1b[0m");
118        println!(
119            "no provider key in the environment (looked for {}).",
120            CANDIDATES
121                .iter()
122                .map(|(_, k)| *k)
123                .collect::<Vec<_>>()
124                .join(", ")
125        );
126        println!("running the keyless demo instead — same proxy, same receipt, local upstream.\n");
127        return crate::demo::run().await;
128    };
129
130    // The proxy runs in-process here, so its logs are the operator's only window into why a call
131    // failed. Without this the kiosk swallows the provider's actual error message.
132    crate::run::init_tracing();
133
134    println!("\n\x1b[1mFirstpass kiosk\x1b[0m");
135    println!(
136        "found {} — routing one real request through a real enforce ladder\n",
137        pick.key_env
138    );
139
140    // Write the config next to the operator, but never over the top of one they already have:
141    // clobbering a tuned routing policy to run a demo would be an unforgivable trade.
142    let path = PathBuf::from("firstpass.toml");
143    let toml = kiosk_config(pick);
144    let config_note = if path.exists() {
145        "firstpass.toml already exists — using it unchanged".to_owned()
146    } else {
147        std::fs::write(&path, &toml)?;
148        format!("wrote {}", path.display())
149    };
150    println!("config   : {config_note}");
151    let toml = std::fs::read_to_string(&path)?;
152
153    let db = std::env::temp_dir().join(format!("firstpass-kiosk-{}.db", uuid::Uuid::now_v7()));
154    let (proxy, _writer) = spawn(&toml, &db).await?;
155    println!("proxy    : {proxy}\n");
156
157    // Exactly the request a caller would make, in the Anthropic wire format the agent tools speak.
158    let key = std::env::var(pick.key_env).unwrap_or_default();
159    let client = reqwest::Client::new();
160    let served: Value = client
161        .post(format!("{proxy}/v1/messages"))
162        .header("x-api-key", &key)
163        .header("authorization", format!("Bearer {key}"))
164        .json(&json!({
165            "model": "claude-haiku-4-5",
166            "max_tokens": 256,
167            "messages": [{
168                "role": "user",
169                "content": "Reply with ONLY a JSON object with keys \"id\" (string) and \"total\" (number). No prose, no code fence.",
170            }],
171        }))
172        .send()
173        .await?
174        .json()
175        .await?;
176
177    if served.get("error").is_some() {
178        // The proxy answers callers with a deliberately generic `engine_error` — an upstream body
179        // can echo request content, so it is logged rather than returned. Here the proxy is
180        // in-process and the operator IS the caller, so the log line above this one already
181        // carries the provider's own words (`provider rejected the call ... body=...`). Point at
182        // it: "no rung could serve a valid response" is true and useless when the real answer is
183        // "that key was rejected".
184        return Err(format!(
185            "the {} call failed — see the `provider rejected the call` line above for the \
186             provider's own message (a rejected key is the usual cause). `firstpass doctor` \
187             checks the key and config.",
188            pick.key_env
189        )
190        .into());
191    }
192    println!("served   : {}", served["content"][0]["text"]);
193    println!("model    : {}\n", served["model"]);
194
195    let trace = wait_for_trace(&db).await.ok_or("no receipt was recorded")?;
196    print_receipt(&trace);
197
198    let all = crate::store::load_all_traces(&db)?;
199    println!(
200        "chain    : {}",
201        if verify_chain(&all, GENESIS_HASH).is_ok() {
202            "\x1b[32mverified ✓\x1b[0m — re-derivable by anyone holding the log"
203        } else {
204            "BROKEN"
205        }
206    );
207    println!("panel    : {proxy}/panel");
208    println!("\nkeep it: FIRSTPASS_CONFIG=./firstpass.toml firstpass up");
209    println!("route your agent: export ANTHROPIC_BASE_URL={proxy}");
210    println!("undo everything : unset ANTHROPIC_BASE_URL\n");
211
212    let _ = std::fs::remove_file(&db);
213    Ok(())
214}
215
216/// The agent-native form of the kiosk: no prose, no colours, no prompts — one structured document
217/// describing what was found, what config would run, whether the pipeline actually works, and the
218/// exact environment variables to route and to leave.
219///
220/// The self-test is deliberately **keyless**: it exercises the whole path (route → gate →
221/// escalate → serve → receipt → chain) against a local upstream, so an agent can confirm the
222/// install is sound without spending the operator's money on a call it did not ask for. Whether a
223/// provider key exists is reported as a fact, not proven by billing it.
224///
225/// Every value is machine-readable. An agent that has to regex a paragraph has not been onboarded.
226pub async fn handshake() -> Value {
227    let mut doc = handshake_static();
228    doc["selftest"] = selftest().await;
229    doc
230}
231
232/// The part of the handshake that needs no runtime: what keys exist, what config would run, and
233/// how to route and unroute. Split out so the MCP server — whose dispatch is synchronous — can
234/// answer the same question without blocking a runtime thread to do it.
235#[must_use]
236pub fn handshake_static() -> Value {
237    let pick = pick_provider(|k| std::env::var(k).ok());
238    let detected: Vec<&str> = CANDIDATES
239        .iter()
240        .filter(|(_, k)| std::env::var(k).is_ok_and(|v| !v.trim().is_empty()))
241        .map(|(_, k)| *k)
242        .collect();
243    let selftest = json!({
244        "ok": null,
245        "reason": "not run here — `firstpass handshake` runs the keyless self-test",
246    });
247    json!({
248        "product": "firstpass",
249        "version": env!("CARGO_PKG_VERSION"),
250        "provider": {
251            "picked": pick.map(|p| p.provider.id()),
252            "key_env": pick.map(|p| p.key_env),
253            "keys_present": detected,
254        },
255        "config": {
256            "path": "firstpass.toml",
257            "exists": std::path::Path::new("firstpass.toml").exists(),
258            // The config is RETURNED, not written: a handshake reports, it does not mutate the
259            // working tree behind the agent's back. `firstpass kiosk` is the command that writes.
260            "toml": pick.map(kiosk_config),
261        },
262        "selftest": selftest,
263        "route_your_agent": { "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080" } },
264        "offboard": { "unset": ["ANTHROPIC_BASE_URL"] },
265        "next": [
266            "firstpass kiosk    — write the config and put one real request through it",
267            "firstpass up       — run the proxy",
268            "firstpass doctor   — validate config, key, and gate binaries",
269        ],
270    })
271}
272
273/// Exercise the whole path — route, gate, escalate, serve, receipt, chain — against a local
274/// upstream. Keyless on purpose: an agent must be able to confirm the install is sound without
275/// spending the operator's money on a call nobody asked for.
276async fn selftest() -> Value {
277    if let Ok(upstream) = crate::demo::spawn_upstream().await {
278        let db =
279            std::env::temp_dir().join(format!("firstpass-handshake-{}.db", uuid::Uuid::now_v7()));
280        if let Ok((proxy, _w)) = crate::demo::spawn_proxy(&upstream, &db).await {
281            let served = reqwest::Client::new()
282                .post(format!("{proxy}/v1/messages"))
283                .header("x-api-key", "keyless-selftest")
284                .json(&json!({
285                    "model": "claude-haiku-4-5",
286                    "max_tokens": 64,
287                    "messages": [{ "role": "user", "content": "selftest" }],
288                }))
289                .send()
290                .await;
291            let ok_http = served.is_ok_and(|r| r.status().is_success());
292            let trace = wait_for_trace(&db).await;
293            let chain_ok = trace
294                .as_ref()
295                .is_some_and(|t| verify_chain(std::slice::from_ref(t), &t.prev_hash).is_ok());
296            let out = json!({
297                "ok": ok_http && trace.is_some() && chain_ok,
298                "keyless": true,
299                "served": ok_http,
300                "receipt": trace.is_some(),
301                "escalated": trace.as_ref().is_some_and(|t| t.attempts.len() > 1),
302                "chain_verified": chain_ok,
303            });
304            let _ = std::fs::remove_file(&db);
305            return out;
306        }
307        let _ = std::fs::remove_file(&db);
308    }
309    json!({ "ok": false, "keyless": true, "reason": "could not stand up the local self-test" })
310}
311
312/// Stand up the real proxy on an ephemeral port with `toml` as its routing config.
313async fn spawn(toml: &str, db: &Path) -> Result<(String, tokio::task::JoinHandle<()>), Fail> {
314    let toml = toml.to_owned();
315    let db_str = db.to_string_lossy().into_owned();
316    let config = crate::ProxyConfig::from_lookup(move |k| match k {
317        "FIRSTPASS_CONFIG_TOML" => Some(toml.clone()),
318        "FIRSTPASS_MODE" => Some("enforce".to_owned()),
319        "FIRSTPASS_DB" => Some(db_str.clone()),
320        _ => None,
321    })?;
322    let provider_defs = config
323        .routing
324        .as_ref()
325        .map(|r| r.providers.as_slice())
326        .unwrap_or_default();
327    let providers = crate::provider::ProviderRegistry::from_config(
328        provider_defs,
329        &config.upstream_anthropic,
330        &config.upstream_openai,
331    );
332    let (traces, writer) = crate::store::open(db)?;
333    let state = crate::proxy::AppState {
334        config: Arc::new(config),
335        http: reqwest::Client::new(),
336        providers,
337        gate_health: Arc::new(crate::gate::GateHealthRegistry::new()),
338        shadow_ledger: Arc::new(crate::shadow::ShadowLedger::new()),
339        guardrails: Arc::new(crate::guard::GuardrailRegistry::new()),
340        traces,
341        adaptive: None,
342        bandit: None,
343        predictor: None,
344        tenant_rate_limiter: None,
345        spill: None,
346    };
347    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
348    let addr = listener.local_addr()?;
349    let app = crate::app(state)?;
350    tokio::spawn(async move {
351        let _ = axum::serve(listener, app).await;
352    });
353    Ok((format!("http://{addr}"), writer))
354}
355
356/// Traces are written off the hot path, so the receipt lands a beat after the response.
357async fn wait_for_trace(db: &Path) -> Option<Trace> {
358    for _ in 0..50 {
359        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
360        if let Ok(traces) = crate::store::load_all_traces(db)
361            && let Some(t) = traces.into_iter().next()
362        {
363            return Some(t);
364        }
365    }
366    None
367}
368
369#[cfg(test)]
370mod tests {
371    use super::*;
372
373    #[test]
374    fn picks_the_first_provider_whose_key_is_present() {
375        let pick = pick_provider(|k| (k == "OPENAI_API_KEY").then(|| "sk-x".to_owned()))
376            .expect("openai key must be found");
377        assert_eq!(pick.provider, Provider::OpenAi);
378        assert_eq!(pick.key_env, "OPENAI_API_KEY");
379
380        // Anthropic wins when both are set — it is first in priority order.
381        let both = pick_provider(|k| {
382            matches!(k, "OPENAI_API_KEY" | "ANTHROPIC_API_KEY").then(|| "sk-x".to_owned())
383        })
384        .expect("a key must be found");
385        assert_eq!(both.provider, Provider::Anthropic);
386
387        assert_eq!(
388            pick_provider(|_| None),
389            None,
390            "no key at all is a supported state, not an error"
391        );
392    }
393
394    /// A leftover `export ANTHROPIC_API_KEY=` in a shell profile is common. Treating it as a key
395    /// would send the kiosk into a guaranteed 401 instead of the demo that always works.
396    #[test]
397    fn a_blank_key_counts_as_absent() {
398        assert_eq!(
399            pick_provider(|k| (k == "ANTHROPIC_API_KEY").then(|| "   ".to_owned())),
400            None
401        );
402    }
403
404    /// The handshake reports; it does not act. An agent calling it to *find out* whether it is
405    /// set up must not discover that asking rewrote the working tree.
406    #[test]
407    fn handshake_is_machine_readable_and_writes_nothing() {
408        let before = std::path::Path::new("firstpass.toml").exists();
409        let doc = handshake_static();
410
411        // Every field an agent needs is a value, not prose it would have to parse.
412        assert_eq!(doc["product"], "firstpass");
413        assert!(doc["version"].is_string());
414        assert!(doc["provider"]["keys_present"].is_array());
415        assert!(doc["config"]["exists"].is_boolean());
416        assert!(doc["route_your_agent"]["env"]["ANTHROPIC_BASE_URL"].is_string());
417        // Offboarding stays one env var — the invariant the whole product rests on.
418        assert_eq!(doc["offboard"]["unset"][0], "ANTHROPIC_BASE_URL");
419        // The static form must not claim a self-test it did not run.
420        assert!(doc["selftest"]["ok"].is_null());
421
422        assert_eq!(
423            std::path::Path::new("firstpass.toml").exists(),
424            before,
425            "handshake must not create or remove config"
426        );
427    }
428
429    /// The kiosk must emit config the parser actually accepts, for every provider it can pick —
430    /// a config that fails to parse would turn the one-press button into a stack trace.
431    #[test]
432    fn every_pickable_provider_yields_a_parseable_enforcing_config() {
433        for (provider, key_env) in CANDIDATES {
434            let toml = kiosk_config(Pick { provider, key_env });
435            let cfg = firstpass_core::Config::parse(&toml)
436                .unwrap_or_else(|e| panic!("{provider:?} kiosk config must parse: {e}"));
437            assert_eq!(
438                cfg.routes[0].mode,
439                Mode::Enforce,
440                "{provider:?} must enforce, or the receipt shows no decision"
441            );
442            // Parse enforces that every rung is priced, so the receipt cannot report a $0.00
443            // spend it never measured — assert the ladder is actually populated.
444            assert!(
445                cfg.routes[0].ladder.len() >= 2,
446                "{provider:?} needs a rung to escalate to"
447            );
448        }
449    }
450}