supercode_harness/
lib.rs

1//! # supercode
2//!
3//! A lightweight, fully-customizable AI coding-agent SDK in Rust.
4//!
5//! `supercode` is a native agent loop — it talks directly to any model through
6//! [OpenRouter](https://openrouter.ai) (or any other OpenAI-compatible endpoint),
7//! drives a configurable set of tools, and is designed to be a superset of what
8//! tools like Claude Code and Codex can do: every prompt, every tool description,
9//! and every tool's on/off state is yours to control.
10//!
11//! ## Quick start
12//!
13//! ```no_run
14//! use supercode_harness::{Agent, Config};
15//!
16//! # async fn run() -> supercode_harness::Result<()> {
17//! // Reads OPENROUTER_API_KEY from the environment by default.
18//! let config = Config::builder()
19//!     .model("anthropic/claude-opus-4-8")
20//!     .system_prompt("You are a terse, expert pair programmer.")
21//!     .build();
22//!
23//! let mut agent = Agent::new(config)?;
24//! let reply = agent.send("List the files in the current directory.").await?;
25//! println!("{reply}");
26//! # Ok(())
27//! # }
28//! ```
29//!
30//! ## Design
31//!
32//! - [`Config`] — the single knob box: model, endpoint, credentials, sampling,
33//!   the system prompt, and per-tool overrides (enable/disable + custom
34//!   descriptions).
35//! - [`Provider`] — the model transport. [`OpenAiProvider`] speaks the
36//!   OpenAI chat-completions wire format and defaults to OpenRouter, so it
37//!   reaches Claude, GPT, Gemini, Llama, and anything else OpenRouter exposes.
38//! - [`Tool`] / [`ToolRegistry`] — the capability surface. Built-ins cover
39//!   file read/write/edit, directory listing, glob, content search, and shell
40//!   execution. Register your own to extend it.
41//! - [`Agent`] — the loop that ties it together: it streams a turn, runs any
42//!   tool calls the model requests, feeds results back, and repeats until the
43//!   model produces a final answer.
44
45#![warn(missing_docs)]
46
47#[cfg(feature = "adapter-acp")]
48pub mod acp_frontend;
49#[cfg(feature = "adapter-acp")]
50pub mod acp_server;
51mod agent;
52pub mod audit;
53pub mod background;
54pub mod catalog;
55pub mod checkpoint;
56pub mod claude_compat;
57pub mod claude_peer;
58pub mod claude_runtime_scheduler;
59pub mod claude_runtime_state;
60pub mod codex_peer;
61mod config;
62pub mod configfile;
63mod error;
64mod event;
65pub mod fidelity;
66pub mod formatters;
67#[cfg(feature = "adapter-api")]
68pub mod frontend;
69#[cfg(not(feature = "adapter-api"))]
70#[allow(dead_code)]
71mod frontend;
72#[allow(missing_docs)]
73mod frontend_contract_generated;
74pub mod git_metadata;
75pub mod harness_auth;
76#[cfg(feature = "adapter-api")]
77pub mod harness_service;
78#[cfg(not(feature = "adapter-api"))]
79#[allow(dead_code)]
80mod harness_service;
81pub mod human_export;
82pub mod interop_settings;
83pub mod live_runtime;
84pub mod lsp;
85pub mod mcp;
86pub mod mcp_oauth;
87mod message;
88pub mod model_catalog;
89pub mod model_change;
90pub mod modules;
91pub mod permissions;
92pub mod plugins;
93pub mod presets;
94pub mod pricing_ref;
95mod provider;
96pub mod reduce;
97pub mod runtime;
98pub mod runtime_lease;
99#[cfg(feature = "adapter-api")]
100pub mod runtime_registry;
101mod safe_path;
102pub mod sandbox;
103pub mod schema;
104pub mod sdk;
105#[cfg(feature = "adapter-api")]
106pub mod server;
107#[cfg(not(feature = "adapter-api"))]
108#[allow(dead_code, unused_imports)]
109mod server;
110pub mod session;
111pub mod session_activity;
112pub mod session_index;
113pub mod session_title;
114pub mod session_tree;
115pub mod sidecar;
116pub mod store;
117pub mod subagents;
118pub mod support;
119pub mod tokens;
120pub mod tools;
121pub mod tui;
122pub mod usage_log;
123pub mod watch;
124
125#[cfg(feature = "adapter-acp")]
126pub use acp_frontend::{AcpFrontendCheckpoint, AcpFrontendConnectOptions, AcpFrontendRuntime};
127pub use agent::Agent;
128pub use catalog::{
129    DiscoveryPage, DiscoveryQuery, HarnessCatalog, HarnessHomes, HarnessId, SessionDescriptor,
130    SessionLocator, StorageLocator,
131};
132pub use claude_peer::{
133    message_claude_peer, read_claude_peer_settings, read_registry as read_claude_peer_registry,
134    update_claude_peer_settings, user_settings_path as claude_user_settings_path,
135    write_claude_peer_settings, ClaudeCrossSessionInbound, ClaudePeerDelivery, ClaudePeerEndpoint,
136    ClaudePeerRefusal, ClaudePeerRefusalError, ClaudePeerSession, ClaudePeerSettings,
137    ClaudePeerSettingsError, ClaudePeerStatus, CourierRunner, ProcessCourierRunner,
138};
139pub use claude_runtime_scheduler::{
140    ClaudeCronScheduleState, ClaudeRuntimeDeliveryState, ClaudeRuntimeSchedulerState,
141    ClaudeRuntimeTrigger, ClaudeRuntimeTriggerKind, ClaudeWakeupScheduleState,
142};
143pub use claude_runtime_state::{
144    ClaudeBackgroundChild, ClaudeBackgroundState, ClaudeCronJob, ClaudeQueueState,
145    ClaudeRuntimeExecutionState, ClaudeRuntimeManifest, ClaudeRuntimePosture, ClaudeRuntimeResidue,
146    ClaudeWakeup, CLAUDE_RUNTIME_MANIFEST_VERSION,
147};
148pub use config::{
149    ApprovalPolicy, CachePlan, Config, ConfigBuilder, ConfigFile, ConfigProfile,
150    ContextInjectionBlock, SteeringMode, StopGateHook, ToolAdvertising, ToolOverride,
151    ToolOverrideProfile, DEFAULT_SYSTEM_PROMPT,
152};
153pub use configfile::HarnessConfig;
154pub use interop_settings::{
155    configure_harness_interop_settings, inspect_harness_interop_settings, HarnessAdvisorySeverity,
156    HarnessInteropAdvisory, HarnessInteropControl, HarnessInteropSettingsError,
157    HarnessInteropSettingsReport, HarnessSettingChange, HarnessSettingChoice,
158    HarnessSettingRecommendation, HarnessSettingScope, CLAUDE_CROSS_SESSION_INBOUND_KEY,
159    HARNESS_INTEROP_SETTINGS_SCHEMA,
160};
161pub use live_runtime::{
162    discover_live_runtime, find_live_runtime, forget_live_runtime, list_live_runtimes,
163    register_live_runtime, register_live_runtime_with_metadata, resolve_live_runtime,
164    LiveRuntimeEndpoint, LiveRuntimeMetadata, LiveRuntimeReceiptError, LiveRuntimeRecord,
165    LiveRuntimeRegistration, LiveRuntimeSource, LiveRuntimeSupervisor, ResolvedLiveRuntime,
166};
167pub use modules::{ModuleActivation, ModuleId};
168
169/// Format an agent's final reply for output. `json` wraps it as
170/// `{"result": "..."}`; otherwise the reply is returned as-is. The
171/// stream-json form is the live [`AgentEvent`] stream via an [`EventSink`].
172pub fn format_reply(reply: &str, json: bool) -> String {
173    if json {
174        serde_json::json!({ "result": reply }).to_string()
175    } else {
176        reply.to_string()
177    }
178}
179pub use error::{Error, Result};
180pub use event::{AgentEvent, EventSink};
181pub use fidelity::{
182    core_messages, measure_fidelity, messages_equal, messages_equal_multimodal, replay_eligible,
183    Fidelity, FidelityMetric, FidelityResidue,
184};
185#[cfg(feature = "adapter-api")]
186pub use frontend::HttpFrontendRuntime;
187pub use frontend::{
188    FrontendActions, FrontendApprovalDecision, FrontendAttachSnapshot, FrontendAttachment,
189    FrontendCommandDescriptor, FrontendConnectionState, FrontendDisplayCapabilities,
190    FrontendElicitationAction, FrontendEvent, FrontendOperationDescriptor,
191    FrontendOperationInvocation, FrontendOperationKind, FrontendOperationResult, FrontendRequest,
192    FrontendRequestKind, FrontendResponse, FrontendRuntime, FrontendRuntimeDescriptor,
193    FrontendRuntimeError, FrontendRuntimeMetadata, FrontendTurnState, FRONTEND_REPLAY_CAPACITY,
194    FRONTEND_RUNTIME_SCHEMA_VERSION,
195};
196pub use frontend_contract_generated::{
197    FrontendFacadeMethod, FrontendFacadeTransport, GeneratedFrontendClient,
198};
199pub use harness_auth::{
200    harness_authentication_methods, harness_authentication_plan, inspect_harness_authentication,
201    HarnessAuthenticationEnvironment, HarnessAuthenticationError, HarnessAuthenticationInteraction,
202    HarnessAuthenticationLaunch, HarnessAuthenticationMethod, HarnessAuthenticationMethodId,
203    HarnessAuthenticationPlan, HarnessAuthenticationReport, HarnessAuthenticationState,
204    HarnessBrowserBehavior, HARNESS_AUTHENTICATION_SCHEMA,
205};
206pub use harness_service::{
207    HarnessSessionService, HARNESS_SERVICE_VERSION, RUNTIME_EVENT_METHOD,
208    SESSION_ACTIVITY_EVENT_METHOD, SESSION_EVENT_METHOD, SESSION_INDEX_EVENT_METHOD,
209};
210pub use message::{
211    is_tool_error, mark_tool_error, mark_tool_outcome_unknown, tool_outcome, ChatMessage,
212    FunctionCall, Role, ToolCall, ToolOutcome, TOOL_ERROR_METADATA_KEY,
213    TOOL_OUTCOME_UNKNOWN_METADATA_KEY,
214};
215pub use provider::{
216    model_context_limit, ChatRequest, OpenAiProvider, PromptTokensDetails, Provider, ToolSchema,
217    Usage, UNKNOWN_MODEL_CONTEXT_FLOOR,
218};
219#[cfg(feature = "adapter-api")]
220pub use runtime::SupercodeHttpRuntimeBackend;
221pub use runtime::{
222    AcpRuntimeBackend, ClaudeCodeRuntimeBackend, CodexRuntimeBackend, HarnessEvent,
223    OpenCodeRuntimeBackend, PiRuntimeBackend, RuntimeAttachRequest, RuntimeBackend,
224    RuntimeCapabilities, RuntimeConnection, RuntimeEndpoint, RuntimeHandle, RuntimeInput,
225    RuntimeLaunch, RuntimeStartRequest,
226};
227pub use runtime_lease::{
228    CoordinatedRuntime, CoordinatedRuntimeClient, RuntimeAuthorization, RuntimeClientId,
229    RuntimeControllerLease, RuntimeLeaseCoordinator, RuntimeLeaseError, RuntimeLeaseSnapshot,
230    RuntimeObserverLease, RuntimePermission, DEFAULT_RUNTIME_LEASE_TTL_MS,
231};
232#[cfg(feature = "adapter-api")]
233pub use runtime_registry::{
234    LocalRuntimeRegistry, RuntimeRegistryEntry, RuntimeRegistryEvent, RuntimeRegistryOwner,
235    RuntimeRegistryQuery, RuntimeRegistryState, RuntimeRegistryWatch,
236};
237pub use sandbox::{landlock_available, netns_available, SandboxEnvPolicy, SandboxEscalation};
238pub use sdk::{
239    create_agent, discover_session_page, discover_sessions, load_session, load_session_path,
240    resume_agent, submit_agent, submit_agent_with_images, RuntimeSubmitError, SdkAgent,
241    SdkCapabilities, SdkError, SdkErrorCode, SdkEvent, SdkOperation, SdkPromptSource, SdkRequest,
242    SdkRuntime, SdkRuntimeEvent, SdkService, SDK_SCHEMA_VERSION,
243};
244pub use server::RpcEngine;
245pub use session::{Session, SessionFormat, SessionMeta, SessionSource};
246pub use session_activity::{
247    SessionActivity, SessionActivityEvidence, SessionPresence, SessionTurnState,
248};
249pub use session_index::{SessionIndexChange, SessionIndexDelta, SessionIndexKey};
250pub use store::{SessionInfo, SessionStore};
251pub use support::{
252    harness_support, harness_support_registry, HarnessSupportDescriptor, ImplementationKind,
253    NativeSupport, RuntimeSupport, SupportRegistryReport, SUPPORT_REGISTRY_SCHEMA,
254};
255pub use tools::{
256    shell_sandbox_unenforceable, SandboxPolicy, SchemaTier, Tool, ToolContext, ToolRegistry,
257    WriteObserver,
258};
259pub use watch::{SessionFollower, SessionSnapshotReason, SessionWatchEvent};
supercode_harness/lib.rs

supercode_harness/
lib.rs
