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
//! Worker SDK for [Kruxia Flow](https://kruxiaflow.com) — run Rust
//! activities in budgeted workflows with engine-enforced cost limits.
//!
//! A Kruxia Flow *worker* polls the server for queued activities, executes
//! registered handlers, and reports results (including LLM usage, so
//! external activities count against workflow budgets with full fidelity).
//! This crate provides the complete worker loop: registration, polling,
//! bounded concurrency, heartbeats, timeout and panic containment,
//! completion/failure reporting, OAuth2 client-credentials auth, and
//! graceful drain on shutdown.
//!
//! # Quickstart
//!
//! Run a server locally (no auth needed in dev mode):
//!
//! ```text
//! kruxiaflow serve --insecure-dev
//! ```
//!
//! Then a minimal worker:
//!
//! ```no_run
//! use kruxiaflow_worker::{ActivityContext, ActivityResult, Worker};
//! use serde_json::json;
//!
//! #[derive(serde::Deserialize)]
//! struct EchoParams {
//! message: String,
//! }
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//! let worker = Worker::builder()
//! .worker("demo") // the workflow definition's `worker:` field
//! .register_fn("echo", |params: EchoParams, _ctx: ActivityContext| async move {
//! Ok(ActivityResult::value("echoed", json!(params.message)))
//! })
//! .build()?; // config from KRUXIAFLOW_* environment variables
//!
//! worker.run_until_shutdown().await;
//! Ok(())
//! }
//! ```
//!
//! A workflow activity with `worker: demo` and `name: echo` now executes on
//! this worker.
//!
//! # Reporting cost and usage
//!
//! Activities that call LLMs themselves report per-call usage so the engine
//! records it exactly like built-in LLM activities — visible in cost
//! history/analytics and counted against workflow budgets:
//!
//! ```no_run
//! use kruxiaflow_worker::{ActivityResult, UsageEntry};
//! use serde_json::json;
//!
//! # fn example() -> ActivityResult {
//! ActivityResult::value("summary", json!("..."))
//! .push_usage(
//! UsageEntry::new("anthropic", "claude-sonnet-5")
//! .input_tokens(12034)
//! .output_tokens(512)
//! .cache_read_tokens(9800),
//! )
//! # }
//! ```
//!
//! The server prices entries from its model catalog unless an entry carries
//! an explicit `cost_usd`. Failures spend money too: attach usage to
//! [`ActivityError`] so failed attempts are budget-counted.
//!
//! # Failure semantics
//!
//! Handlers return `Result<ActivityResult, ActivityError>`. Construct errors
//! with [`ActivityError::retryable`] (transient: the orchestrator re-queues
//! up to the activity's retry limit) or [`ActivityError::terminal`] (bad
//! input, business rejection: no retry). Panics and timeouts are caught and
//! reported as retryable; parameter deserialization failures are terminal.
//!
//! # Shutdown
//!
//! [`Worker::run_until_shutdown`] listens for SIGINT/SIGTERM;
//! [`Worker::handle`] gives a programmatic trigger. Shutdown stops polling
//! and drains in-flight activities up to the configured `shutdown_timeout`,
//! then fails the remainder as retryable so they re-queue — nothing is lost
//! or double-completed.
pub use ;
pub use ;
pub use ActivityContext;
pub use ;
pub use WorkerPoller;
pub use ;
pub use ActivityResult;
pub use ;
pub use ;
// Implementing [`ActivityImpl`]/[`TypedActivity`] requires the same
// `async_trait` attribute the traits are declared with; re-exported so
// consumers don't need the direct dependency.
pub use async_trait;