appam 0.1.1

High-throughput, traceable, reliable Rust agent framework for long-horizon AI sessions and easy extensibility
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

//! Legacy web helpers and the trace visualizer server.
//!
//! Most of this module is historical scaffolding from Appam's old web API
//! experiment. The full agent-management API is intentionally hard-disabled for
//! security reasons, but the trace visualizer helpers remain available for
//! local inspection of trace files.

pub mod fs_operations;
pub mod middleware;
pub mod routes;
pub mod session;
pub mod state;
pub mod streaming;
pub mod trace_models;
pub mod trace_parser;
pub mod trace_routes;

pub use state::AppState;

use axum::Router;
use std::net::SocketAddr;
use tower_http::cors::{Any, CorsLayer};
use tower_http::trace::TraceLayer;
use tracing::info;

/// Hard-disable the legacy web API while retaining the code for future work.
const EXPERIMENTAL_WEB_API_ENABLED: bool = false;

/// Attempt to start the legacy web API server.
///
/// Creates an axum server with all routes, middleware, and state configured.
/// Binds to the specified host and port and runs until shutdown.
///
/// # Parameters
///
/// - `host`: Host address to bind to (e.g., "0.0.0.0")
/// - `port`: Port to listen on
/// - `agents_dir`: Directory containing agent TOML files
///
/// # Errors
///
/// Returns an error if the server fails to start or bind to the address.
pub async fn serve(host: String, port: u16, agents_dir: std::path::PathBuf) -> anyhow::Result<()> {
    if !EXPERIMENTAL_WEB_API_ENABLED {
        anyhow::bail!(
            "The Appam web API is experimental and currently disabled for security reasons."
        );
    }

    info!("Starting Appam Web API server");
    info!(host = %host, port = port, "Server configuration");

    // Create application state
    let state = AppState::new(agents_dir).await?;
    info!(agents = state.list_agents().len(), "Agents loaded");

    // Configure CORS
    let cors = CorsLayer::new()
        .allow_origin(Any)
        .allow_methods(Any)
        .allow_headers(Any);

    // Build router with all routes
    let app = Router::new()
        .merge(routes::agent_routes())
        .merge(routes::session_routes())
        .merge(routes::chat_routes())
        .layer(cors)
        .layer(TraceLayer::new_for_http())
        .layer(middleware::rate_limit_layer())
        .with_state(state);

    // Bind and serve
    let addr: SocketAddr = format!("{}:{}", host, port).parse()?;
    info!("Server listening on http://{}", addr);
    info!("API Documentation: http://{}/api/docs", addr);

    let listener = tokio::net::TcpListener::bind(addr).await?;
    axum::serve(
        listener,
        app.into_make_service_with_connect_info::<SocketAddr>(),
    )
    .await?;

    Ok(())
}

/// Start the trace visualizer server.
///
/// Creates a lightweight Axum server serving the trace visualizer UI and API
/// endpoints for listing and retrieving trace files.
///
/// # Parameters
///
/// - `host`: Host address to bind to (e.g., "0.0.0.0")
/// - `port`: Port to listen on
/// - `traces_dir`: Directory containing trace files
///
/// # Errors
///
/// Returns an error if the server fails to start or bind to the address.
///
/// # Examples
///
/// ```ignore
/// # use std::path::PathBuf;
/// appam::web::serve_tracing(
///     "127.0.0.1".to_string(),
///     8080,
///     PathBuf::from("logs")
/// ).await.unwrap();
/// ```
pub async fn serve_tracing(
    host: String,
    port: u16,
    traces_dir: std::path::PathBuf,
) -> anyhow::Result<()> {
    use std::sync::Arc;

    info!("Starting Appam Trace Visualizer");
    info!(host = %host, port = port, traces_dir = %traces_dir.display(), "Server configuration");

    // Ensure traces directory exists
    if !traces_dir.exists() {
        anyhow::bail!("Traces directory does not exist: {}", traces_dir.display());
    }

    // Create trace state
    let state = Arc::new(trace_routes::TraceState::new(traces_dir));

    // Configure CORS
    let cors = CorsLayer::new()
        .allow_origin(Any)
        .allow_methods(Any)
        .allow_headers(Any);

    // Build router with trace routes
    let app = trace_routes::trace_routes()
        .layer(cors)
        .layer(TraceLayer::new_for_http())
        .with_state(state);

    // Bind and serve
    let addr: SocketAddr = format!("{}:{}", host, port).parse()?;
    info!("Trace Visualizer listening on http://{}", addr);
    info!("Open in browser: http://{}", addr);

    let listener = tokio::net::TcpListener::bind(addr).await?;
    axum::serve(
        listener,
        app.into_make_service_with_connect_info::<SocketAddr>(),
    )
    .await?;

    Ok(())
}