Skip to main content

kesa/
lib.rs

1//! Pi - Native AI coding agent CLI
2//!
3//! This library provides the core functionality for the Pi CLI tool,
4//! a Rust port of pi-mono (TypeScript) with emphasis on:
5//! - Performance-oriented native architecture with instrumented startup and TUI paths
6//! - Reliability through explicit errors, bounded cancellation, and conformance tests
7//! - Distribution through one supported end-user binary in official release archives
8//!
9//! ## Public API policy
10//!
11//! The `pi` crate is primarily the implementation crate for the `pi` CLI binary.
12//! External consumers should treat non-`sdk` modules/types as **unstable**
13//! and subject to change. Use [`sdk`] as the stable library-facing surface.
14//!
15//! Currently intended stable exports:
16//! - [`Error`]
17//! - [`PiResult`]
18//! - [`sdk`] module
19
20#![forbid(unsafe_code)]
21// rch clippy probes without these allowances still expose broad, cross-module
22// dormant surfaces in extension/session/SDK paths. The no-allow inventory is
23// tracked in bd-63x3v.5.1; keep this crate-wide guard until the remaining
24// subsystems are narrowed in their own patches.
25// `unused_async_trait_impl` is the nightly-2026-07-05 successor of
26// `unused_async` for async-trait impl fns (new lint name, so the existing
27// allow does not cover it); same rationale as above.
28#![allow(dead_code, clippy::unused_async, clippy::unused_async_trait_impl)]
29#![cfg_attr(
30    test,
31    allow(
32        unused_variables,
33        clippy::assertions_on_constants,
34        clippy::match_same_arms,
35        clippy::uninlined_format_args,
36        clippy::missing_const_for_fn,
37        clippy::collapsible_if
38    )
39)]
40// Allow pedantic lints during early development - can tighten later
41#![allow(
42    clippy::must_use_candidate,
43    clippy::doc_markdown,
44    clippy::missing_errors_doc,
45    clippy::missing_panics_doc,
46    clippy::module_name_repetitions,
47    clippy::similar_names,
48    clippy::wildcard_imports
49)]
50
51// Allow in-crate tests that include integration test helpers to resolve `kesa::...`
52// paths the same way integration tests do.
53extern crate self as kesa;
54
55/// Serialize unit tests that temporarily change the process-wide current
56/// directory. Rust's test runner executes modules concurrently, so separate
57/// per-module locks do not prevent one module from observing another module's
58/// temporary directory.
59#[cfg(test)]
60pub(crate) fn test_current_dir_lock() -> std::sync::MutexGuard<'static, ()> {
61    static LOCK: std::sync::OnceLock<std::sync::Mutex<()>> = std::sync::OnceLock::new();
62    LOCK.get_or_init(|| std::sync::Mutex::new(()))
63        .lock()
64        .unwrap_or_else(std::sync::PoisonError::into_inner)
65}
66
67// Gap H: jemalloc allocator for allocation-heavy paths.
68// Declared in the library so all project binaries/tests share allocator behavior.
69// BSD-family targets stay on their platform allocator to avoid allocator-domain
70// mismatch across libc/pthread and C dependencies such as QuickJS.
71#[cfg(all(feature = "jemalloc", any(target_os = "linux", target_os = "macos")))]
72#[global_allocator]
73static GLOBAL_ALLOCATOR: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
74
75#[doc(hidden)]
76pub mod acp;
77#[doc(hidden)]
78pub mod agent;
79#[doc(hidden)]
80pub mod agent_cx;
81#[doc(hidden)]
82pub mod app;
83#[doc(hidden)]
84pub mod auth;
85#[doc(hidden)]
86pub mod autocomplete;
87#[doc(hidden)]
88pub mod buffer_shim;
89#[doc(hidden)]
90pub mod cli;
91#[doc(hidden)]
92pub mod compaction;
93#[doc(hidden)]
94pub mod compaction_worker;
95#[doc(hidden)]
96pub mod config;
97#[doc(hidden)]
98pub mod conformance;
99#[doc(hidden)]
100pub mod conformance_shapes;
101#[doc(hidden)]
102pub mod connectors;
103#[doc(hidden)]
104pub mod crypto_shim;
105#[doc(hidden)]
106pub mod doctor;
107#[doc(hidden)]
108pub(crate) mod embedded_assets;
109#[doc(hidden)]
110pub mod env;
111pub mod error;
112#[doc(hidden)]
113pub mod error_hints;
114#[doc(hidden)]
115pub mod extension_conformance_matrix;
116#[doc(hidden)]
117pub mod extension_dispatcher;
118#[doc(hidden)]
119pub mod extension_events;
120#[doc(hidden)]
121pub mod extension_inclusion;
122#[doc(hidden)]
123pub mod extension_index;
124#[doc(hidden)]
125pub mod extension_license;
126#[doc(hidden)]
127pub mod extension_popularity;
128#[doc(hidden)]
129pub mod extension_preflight;
130#[doc(hidden)]
131pub mod extension_replay;
132#[doc(hidden)]
133pub mod extension_scoring;
134#[doc(hidden)]
135pub mod extension_tools;
136#[doc(hidden)]
137pub mod extension_validation;
138#[doc(hidden)]
139pub mod extensions;
140#[doc(hidden)]
141pub mod extensions_js;
142#[doc(hidden)]
143pub mod file_lock;
144#[doc(hidden)]
145pub mod flake_classifier;
146#[doc(hidden)]
147pub mod hooks;
148#[doc(hidden)]
149pub mod hostcall_amac;
150#[doc(hidden)]
151pub mod hostcall_io_uring_lane;
152#[doc(hidden)]
153pub mod hostcall_queue;
154#[doc(hidden)]
155pub mod hostcall_rewrite;
156#[doc(hidden)]
157pub mod hostcall_s3_fifo;
158#[doc(hidden)]
159pub mod hostcall_superinstructions;
160#[doc(hidden)]
161pub mod hostcall_trace_jit;
162#[doc(hidden)]
163pub mod http;
164#[doc(hidden)]
165pub mod http_shim;
166#[cfg(feature = "tui")]
167#[doc(hidden)]
168pub mod interactive;
169#[doc(hidden)]
170pub mod keybindings;
171#[doc(hidden)]
172pub mod migrations;
173#[doc(hidden)]
174pub mod model;
175#[doc(hidden)]
176pub mod model_routing;
177#[doc(hidden)]
178pub mod model_selector;
179#[doc(hidden)]
180pub mod models;
181#[doc(hidden)]
182pub mod package_manager;
183#[doc(hidden)]
184pub mod perf_build;
185#[doc(hidden)]
186pub mod permissions;
187#[cfg(feature = "wasm-host")]
188#[doc(hidden)]
189pub mod pi_wasm;
190#[doc(hidden)]
191pub mod platform;
192#[doc(hidden)]
193pub mod provider;
194#[doc(hidden)]
195pub mod provider_metadata;
196#[doc(hidden)]
197pub mod providers;
198#[doc(hidden)]
199pub mod resource_governor;
200#[doc(hidden)]
201pub mod resources;
202#[doc(hidden)]
203pub mod rpc;
204pub mod sandbox;
205#[doc(hidden)]
206pub mod scheduler;
207pub mod sdk;
208#[doc(hidden)]
209pub mod semantic_workspace_graph;
210#[doc(hidden)]
211pub mod session;
212#[doc(hidden)]
213pub mod session_index;
214#[doc(hidden)]
215pub mod session_metrics;
216#[cfg(feature = "tui")]
217#[doc(hidden)]
218pub mod session_picker;
219#[cfg(feature = "sqlite-sessions")]
220#[doc(hidden)]
221pub mod session_sqlite;
222#[doc(hidden)]
223pub mod session_store_v2;
224#[doc(hidden)]
225pub mod sse;
226#[doc(hidden)]
227pub mod subagents;
228#[doc(hidden)]
229pub mod swarm_activity_ledger;
230#[doc(hidden)]
231pub mod swarm_flight_recorder;
232#[doc(hidden)]
233pub mod swarm_progress_slo;
234#[doc(hidden)]
235pub mod swarm_replay;
236#[doc(hidden)]
237pub mod terminal_images;
238#[doc(hidden)]
239pub mod theme;
240#[doc(hidden)]
241pub mod todo;
242#[doc(hidden)]
243pub mod tool_policy;
244#[doc(hidden)]
245pub mod tools;
246#[doc(hidden)]
247pub mod tui;
248#[doc(hidden)]
249pub mod validation_broker;
250#[doc(hidden)]
251pub mod vcr;
252#[doc(hidden)]
253pub mod version_check;
254#[doc(hidden)]
255pub mod web_tools;
256
257pub use error::{Error, Result as PiResult};
258#[doc(hidden)]
259pub use extension_dispatcher::ExtensionDispatcher;
260
261// Conditional re-exports for fuzz harnesses.
262// These expose internal parsing functions that are normally private,
263// gated behind the `fuzzing` feature so they do not appear in the
264// public API during normal builds.
265#[cfg(feature = "fuzzing")]
266#[doc(hidden)]
267pub mod fuzz_exports {
268    //! Re-exports of internal parsing/deserialization functions for
269    //! `cargo-fuzz` / `libFuzzer` harnesses.
270    //!
271    //! Enabled only when the `fuzzing` Cargo feature is active.
272    //! The `fuzz/Cargo.toml` depends on this crate with
273    //! `features = ["fuzzing"]`.
274
275    pub use crate::config::Config;
276    pub use crate::model::{
277        AssistantMessage, ContentBlock, Message, StreamEvent, TextContent, ThinkingContent,
278        ToolCall, ToolResultMessage, Usage, UserContent, UserMessage,
279    };
280    pub use crate::session::{Session, SessionEntry, SessionHeader, SessionMessage};
281    pub use crate::sse::{SseEvent, SseParser};
282    pub use crate::tools::{fuzz_normalize_dot_segments, fuzz_resolve_path};
283
284    // Provider stream processor wrappers for coverage-guided fuzzing.
285    pub use crate::providers::anthropic::fuzz::Processor as AnthropicProcessor;
286    pub use crate::providers::azure::fuzz::Processor as AzureProcessor;
287    pub use crate::providers::cohere::fuzz::Processor as CohereProcessor;
288    pub use crate::providers::gemini::fuzz::Processor as GeminiProcessor;
289    pub use crate::providers::openai::fuzz::Processor as OpenAIProcessor;
290    pub use crate::providers::openai_responses::fuzz::Processor as OpenAIResponsesProcessor;
291    pub use crate::providers::vertex::fuzz::Processor as VertexProcessor;
292}