cots

cargo add cots

[dependencies]
cots  = "0.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use cots::agents::{AgentClient, AgentConfig};

let agent = AgentClient::new(
    AgentConfig::new("ten_xxxxxxxxxx", "agt_xxxxxxxxxx")
        .with_data_plane_url("http://localhost:9090")
        .with_control_plane_url("http://localhost:8080/api")
        .with_api_key("agk_xxxxxxxxxx"),   // required once the data plane has auth on
);

let agent = AgentClient::new(AgentConfig::from_env()?);

use cots::agents::NormalizedAction;

let result = agent
    .guard(NormalizedAction::new("Slack", "send_slack_message"), || async {
        // send the real Slack message here
        "sent"
    })
    .await?;

// result.outcome  is Executed | Blocked | Timeout
// result.decision is "allowed" | "blocked" | "require_approval"
// result.detail   is Some(<your closure’s return>) only when it actually ran

let action = NormalizedAction {
    principal_id: Some("user_42".into()),
    session_id: Some("sess_abc".into()),
    data_classification: Some("pii".into()),
    risk_score: Some(70),
    amount: Some(2500.0),
    recipient: Some("finance@acme.com".into()),
    ..NormalizedAction::new("Payments", "transfer_funds")
};

use cots::agents::GovernedOutcome;

match result.outcome {
    GovernedOutcome::Executed => println!("ran: {:?}", result.detail),
    GovernedOutcome::Blocked  => println!("blocked by {:?}", result.matched_rules),
    GovernedOutcome::Timeout  => println!("no approval in time"),
}

use cots::agents::ApprovalOutcome;

// One request to POST {data_plane_url}/v1/intercept — no waiting, no execution.
let verdict = agent.intercept(NormalizedAction::new("Slack", "send_slack_message")).await?;
// verdict: InterceptResult { action_event_id, tenant_id, decision, status, matched_rules, latency_ms }

if verdict.decision == "require_approval" {
    match agent.wait_for_approval(&verdict.action_event_id).await? {
        ApprovalOutcome::Approved => { /* do the work */ }
        ApprovalOutcome::Denied   => { /* abort */ }
        ApprovalOutcome::Timeout  => { /* gave up after approval_timeout_ms */ }
    }
}

let cp = &agent.control_plane;

// 1. Register the org (returns the tenant + seeded admin/approver users).
let reg = cp.register_tenant("Srotas Space Pvt Ltd", Some("admin-password")).await?;

// 2. Authenticate as that admin before anything else.
cp.login(&reg.admin_user.email, "admin-password").await?;

// 3. Register the agent — its api_key is returned ONCE here; store it.
let created = cp.register_agent("Ops Agent").await?;
let api_key = created.api_key.expect("shown once at registration");

// 4. Declare what this agent may do, then activate it.
cp.create_action_surface(&created.agent_id, "Slack", &["send_slack_message"]).await?;
let pep = cp.activate_agent(&created.agent_id).await?;   // PepConfig for the interceptor

let cp = &agent.control_plane;

// Everything waiting on a human, for this tenant:
let pending = cp.list_pending_approvals(&tenant_id).await?;

for req in pending {
    // req: ApprovalRequest { approval_request_id, action_event_id, status }
    cp.approve(&req.approval_request_id, "looks fine").await?;
    // or: cp.deny(&req.approval_request_id, "over the limit").await?;
}

// Look up the approval attached to a specific action event:
let req = cp.get_approval_for_action(&action_event_id).await?;

// actix-web — examples/with_actix.rs (POST /notify on :8090)
#[actix_web::post("/notify")]
async fn notify(agent: actix_web::web::Data<AgentClient>) -> impl actix_web::Responder {
    let r = agent
        .guard(NormalizedAction::new("Slack", "send_slack_message"), || async { "sent (actix)" })
        .await;
    // ... map r.decision / r.outcome into a JSON response ...
    actix_web::HttpResponse::Ok().finish()
}

// axum — examples/with_axum.rs (POST /notify on :8091)
async fn notify(axum::extract::State(agent): axum::extract::State<std::sync::Arc<AgentClient>>) {
    let _r = agent
        .guard(NormalizedAction::new("Slack", "send_slack_message"), || async { "sent (axum)" })
        .await;
}

cargo run --example with_actix   # actix-web on :8090
cargo run --example with_axum    # axum on :8091
curl -X POST localhost:8090/notify
curl -X POST localhost:8091/notify

// AgentClient — cots::agents
AgentClient::new(config: AgentConfig) -> AgentClient
guard<F, Fut, T>(action, execute: F) -> Result<GovernedResult<T>, SdkError>   // FnOnce -> Future<T>
intercept(action: NormalizedAction) -> Result<InterceptResult, SdkError>
wait_for_approval(action_event_id: &str) -> Result<ApprovalOutcome, SdkError>
control_plane: ControlPlaneClient                              // public field

// AgentConfig — builder + env
AgentConfig::new(tenant_id, agent_id) -> AgentConfig
    .with_data_plane_url(url) .with_control_plane_url(url)
    .with_api_key(key) .with_approval_timeout_ms(ms) .with_approval_poll_ms(ms)
AgentConfig::from_env() -> Result<AgentConfig, SdkError>

// ControlPlaneClient — agent.control_plane
login(email, password) -> LoginResult
register_tenant(name, admin_password: Option<&str>) -> TenantRegistration
register_agent(name) -> Agent                                 // .api_key shown once
create_action_surface(agent_id, target_system, allowed_action_types: &[&str]) -> Value
activate_agent(agent_id) -> PepConfig
get_action(action_event_id) -> ActionEventStatus
get_approval_for_action(action_event_id) -> ApprovalRequest
list_pending_approvals(tenant_id) -> Vec<ApprovalRequest>
approve(approval_request_id, reason) -> Value
deny(approval_request_id, reason) -> Value

// Errors — cots::SdkError
SdkError::Config(String) | SdkError::Http(reqwest::Error) | SdkError::Api { status: u16, body: String }