phi_agent/
lib.rs

1//! phi-agent: Rust AI Agent runtime framework — orchestration, sessions, streaming all built-in.
2//! You only define tools, prompts, and domain knowledge.
3//!
4//! Built on agent-base and agent-works, providing builder factory, renderer,
5//! config resolution, session management, and other infrastructure.
6//! **Ships with zero application tools.** Kernel tools (file I/O, shell,
7//! multi-agent) are available via `phi-kernel-tools` behind feature flags —
8//! all off by default. Application tools are injected by consumers.
9
10#![warn(missing_docs)]
11
12pub mod agent;
13pub mod bridge;
14pub mod cli;
15pub mod config;
16pub mod event_log;
17/// System prompt generation (EN/CN).
18pub mod prompt;
19pub mod render;
20/// Session management — ID resolution, locking, snapshots, cleanup.
21pub mod session;
22
23// ── Common agent-base types ──
24// Only re-export the types consumers use most often.
25// For the full type set, import directly from agent-base.
26//
27// Note: AgentBuilder re-exports agent_works::AgentBuilder (not agent_base::AgentBuilder)
28// because phi-agent is a full-stack framework that includes multi-agent, skills, MCP, etc.
29// For the bare runtime builder, use agent_base::AgentBuilder directly.
30pub use agent_base::{
31    AgentError, AgentResult, AgentRuntime, AllowAllApprovalHandler, ApprovalDecision, ApprovalHandler, ApprovalRequest,
32    ChatMessage, CheckpointData, CheckpointStep, ConsecutiveFailureRecovery, Content, ContextCompaction,
33    ContextWindowManager, DenyAllApprovalHandler, FinishReason, Language, Middleware, PlanItem, PlanStepStatus,
34    PostLlmCtx, PreLlmCtx, ReasoningConfig, ReasoningEffort, RetryOnError, RiskLevel, RunOutcome, RuntimeEvent,
35    SafetyConfig, SessionId, Tool, ToolContext, ToolDecision, ToolMetadata, ToolPolicy, ToolRegistry,
36    TurnFactMiddleware, TurnToolLimitMiddleware, UpdatePlanTool, UserMessageCtx, estimate_messages_tokens,
37    first_system_prompt,
38};
39// Token-budget window strategy — a pure strategy in agent-works (agent-base
40// stays strategy-free: contract + primitives only).
41pub use agent_works::AgentBuilder;
42pub use agent_works::rotation_policy::{
43    DEFAULT_SEED_MESSAGE, TokenBudgetAction, TokenBudgetConfig, TokenBudgetCore, TokenBudgetState,
44    build_context_window_info, token_budget_base_overhead,
45};
46
47// ── phi-telemetry (metrics types and storage) ──
48#[cfg(feature = "telemetry")]
49pub use phi_telemetry::{
50    SessionMetrics, SessionOutcome, SessionSummary, TurnMetrics, TurnOutcome, list_all_metrics, load_metrics,
51    save_metrics, try_load_metrics,
52};
53
54// ── agent-works ──
55#[cfg(feature = "focus")]
56pub use agent_works::focus::{Context as FocusContext, Focus, FocusError, FocusInput, FocusOutput};
57#[cfg(feature = "multi-agent")]
58pub use agent_works::multi_agent::{
59    ChildPermissionMode, ChildReport, ChildResultEvent, ControlConfig, MultiAgentConfig,
60};
61// Child-result fan-in delivery policy — data-only routes; the consumer renders
62// the words. Sunk down from phimint's UI so any multi-agent UI reuses it.
63#[cfg(feature = "multi-agent")]
64pub use agent_works::multi_agent::fan_in::{ChildResultRoute, ChildResultRouter};
65#[cfg(feature = "multi-agent")]
66pub use agent_works::multi_agent::registry::{AgentSnapshot, RegistrySnapshot};
67
68// ── Framework pass-through (facade completion) ──
69// These are the remaining types a product needs to name directly, so its
70// Cargo.toml can depend on `phi-agent` alone. Only actually-consumed items
71// are re-exported — no catch-all facade.
72/// Plan / user lifecycle event types surfaced to consumers.
73pub use agent_base::UserEvent;
74/// Middleware that nudges the model when it nears the turn limit.
75pub use agent_base::engine::max_turns_nudge::{MaxTurnsNudgeConfig, MaxTurnsNudgeMiddleware};
76/// LLM provider trait family (`LlmProvider`, `Protocol`, `config::LlmConfig`):
77/// build a provider with [`create_provider`] and hand it to the runtime.
78pub use agent_base::llm_trait;
79/// Guard policies from agent-works (tool gating, reasoning-only enforcement).
80pub use agent_works::guard::{DefaultGuard, DefaultGuardConfig, ReasoningOnlyAction};
81/// LLM provider factory (resolves protocol/client from an [`llm_trait`] config).
82pub use llm_unified::create_provider;
83
84// ── Kernel tools (feature-gated) ──
85#[cfg(feature = "shell")]
86pub use phi_kernel_tools::local_shell::LocalShellTool;
87
88// ── Skills (feature-gated) ──
89#[cfg(feature = "skill")]
90pub use agent_works::skill::{
91    MAX_CATALOG_SKILLS, Skill, SkillCatalogRefreshMiddleware, SkillResolver, SkillTelemetry, SkillTool,
92    prompt_skill::PromptSkill, refresh_catalog, render_catalog, strip_catalog,
93};
94
95// ── MCP (feature-gated) ──
96#[cfg(feature = "mcp")]
97pub use agent_works::mcp::{McpServeConfig, McpServer, McpServerConfig, McpServerTransport, McpTransport};
98
99// ── phi-agent types ──
100#[cfg(feature = "compression")]
101pub use agent::CompressionMiddleware;
102pub use agent::{
103    PhiAgent, PhiAgentConfig, base_agent_builder, base_agent_builder_no_compression, base_agent_builder_with_excludes,
104    base_agent_builder_with_options, clear_compression_cache, run_compact_session,
105};
106pub use agent_works::prompt::{
107    DynamicToolsFragment, EnvironmentFragment, FragmentContext, PromptFragment, compose_fragments,
108};
109pub use cli::{ApprovalItem, ApprovalMode, AutoApprovalHandler, QueuedApprovalHandler};
110pub use config::{LlmConfig, resolve_llm_config};
111pub use event_log::{event_to_jsonl, event_to_value, save_turn_log};
112pub use prompt::{build_system_prompt, build_system_prompt_cn, build_system_prompt_with_fragments};
113pub use render::{
114    EventRenderer, JsonStreamRenderer, NullRenderer, OutputFormat, create_renderer, create_stdout_renderer,
115};
116pub use session::{
117    SessionContext, SnapshotInfo, cleanup_expired_sessions, create_snapshot, delete_snapshot, list_snapshots,
118    resolve_session, restore_snapshot, validate_session_id, validate_snapshot_name,
119};
120
121/// Format a number with K/M suffixes for display.
122///
123/// - `n < 1_000` → plain number
124/// - `1_000 <= n < 1_000_000` → `{:.1}K`
125/// - `n >= 1_000_000` → `{:.1}M`
126pub fn format_number(n: u64) -> String {
127    if n >= 1_000_000 {
128        format!("{:.1}M", n as f64 / 1_000_000.0)
129    } else if n >= 1_000 {
130        format!("{:.1}K", n as f64 / 1_000.0)
131    } else {
132        n.to_string()
133    }
134}
135
136#[cfg(test)]
137mod proptests {
138    use super::*;
139
140    proptest::proptest! {
141        #[test]
142        fn format_number_never_panics(n: u64) {
143            let _ = format_number(n);
144        }
145
146        #[test]
147        fn format_number_correct_suffix(n: u64) {
148            let s = format_number(n);
149            if n < 1_000 {
150                proptest::prop_assert_eq!(s, n.to_string());
151            } else if n < 1_000_000 {
152                proptest::prop_assert!(s.ends_with('K'), "expected K suffix for {}, got '{}'", n, s);
153            } else {
154                proptest::prop_assert!(s.ends_with('M'), "expected M suffix for {}, got '{}'", n, s);
155            }
156        }
157
158        #[test]
159        fn format_number_boundary_correct(n in 0u64..1_001) {
160            // At the exact boundary (1000), must switch to K
161            let s = format_number(n);
162            if n < 1_000 {
163                proptest::prop_assert!(!s.contains('K'));
164                proptest::prop_assert!(!s.contains('M'));
165            } else {
166                proptest::prop_assert!(s.ends_with('K'));
167            }
168        }
169    }
170}
phi_agent/lib.rs

phi_agent/
lib.rs
