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")]
48/// The supercode ontology (`docs/ONTOLOGY.md`): the one model under sessions and the
49/// orchestration world.
50pub use supercode_interchange::ontology;
51/// The world piece of the ontology: a harness's operational home as one typed value.
52pub use supercode_interchange::world;
53
54pub mod acp_frontend;
55#[cfg(feature = "adapter-acp")]
56pub mod acp_server;
57mod agent;
58pub mod agent_package;
59pub mod approvals;
60pub mod audit;
61pub mod background;
62pub mod browser;
63pub mod catalog;
64pub mod channels;
65pub mod checkpoint;
66pub mod claude_compat;
67pub mod claude_peer;
68pub mod claude_runtime_state;
69pub mod codex_peer;
70mod config;
71pub mod config_schema;
72pub mod configfile;
73pub mod context_injection;
74mod error;
75mod event;
76pub mod fidelity;
77pub mod formatters;
78#[cfg(feature = "adapter-api")]
79pub mod frontend;
80#[cfg(not(feature = "adapter-api"))]
81#[allow(dead_code)]
82mod frontend;
83#[allow(missing_docs)]
84mod frontend_contract_generated;
85pub mod git_metadata;
86pub mod goals;
87pub mod harness_auth;
88pub mod harness_command;
89#[cfg(feature = "adapter-api")]
90pub mod harness_service;
91#[cfg(not(feature = "adapter-api"))]
92#[allow(dead_code)]
93mod harness_service;
94pub mod human_export;
95pub mod interop_settings;
96pub mod jobs;
97pub mod jobs_control;
98pub mod live_runtime;
99pub mod lsp;
100pub mod mcp;
101pub mod mcp_oauth;
102pub mod memory;
103mod message;
104pub mod model_catalog;
105pub mod model_change;
106pub mod modules;
107pub mod orchestrator;
108pub mod orchestrator_door;
109pub mod output_style;
110pub mod parity;
111pub mod path_rules;
112pub mod permissions;
113pub mod plugins;
114pub mod presets;
115pub mod pricing;
116pub mod pricing_ref;
117pub mod profiles;
118pub mod profiles_control;
119mod provider;
120pub mod reduce;
121pub mod routes;
122pub mod runs;
123pub mod runtime;
124pub mod runtime_lease;
125#[cfg(feature = "adapter-api")]
126pub mod runtime_registry;
127mod safe_path;
128pub mod sandbox;
129pub mod schema;
130pub mod sdk;
131#[cfg(feature = "adapter-api")]
132pub mod server;
133#[cfg(not(feature = "adapter-api"))]
134#[allow(dead_code, unused_imports)]
135mod server;
136pub mod session;
137pub mod session_activity;
138pub mod session_index;
139pub mod session_journal;
140pub mod session_title;
141pub mod session_tree;
142pub mod sessions_control;
143pub mod sidecar;
144pub mod skills;
145pub mod skills_control;
146pub mod store;
147pub mod subagents;
148pub mod support;
149pub mod tokens;
150pub mod tools;
151pub mod triggers;
152pub mod trust;
153pub mod tui;
154pub mod turn_record;
155pub mod usage_log;
156pub mod watch;
157pub mod world_doors;
158
159#[cfg(feature = "adapter-acp")]
160pub use acp_frontend::{AcpFrontendCheckpoint, AcpFrontendConnectOptions, AcpFrontendRuntime};
161pub use agent::{Agent, ContextUsage};
162pub use approvals::{
163    approval_harnesses, lists_approvals, plan_reply, ApprovalChoice, ApprovalDecision,
164    ApprovalDoor, ApprovalKind, ApprovalOption, ApprovalRegistry, ApprovalResolution,
165    ApprovalResolveError, ApprovalRow, ApprovalStatus, ApprovalsQuery, ApprovalsResolveParams,
166};
167pub use catalog::{
168    orchestrator_profile_dirs, DiscoveryPage, DiscoveryQuery, HarnessCatalog, HarnessHomes,
169    HarnessId, SessionDescriptor, SessionLocator, StorageLocator,
170};
171pub use channels::{
172    channel_status, list_channels, ChannelError, ChannelRow, ChannelStatus, CHANNELS_SCHEMA,
173    CHANNEL_HARNESSES,
174};
175pub use claude_peer::{
176    message_claude_peer, read_claude_peer_settings, read_registry as read_claude_peer_registry,
177    update_claude_peer_settings, user_settings_path as claude_user_settings_path,
178    write_claude_peer_settings, ClaudeCrossSessionInbound, ClaudePeerDelivery, ClaudePeerEndpoint,
179    ClaudePeerRefusal, ClaudePeerRefusalError, ClaudePeerSession, ClaudePeerSettings,
180    ClaudePeerSettingsError, ClaudePeerStatus, CourierRunner, ProcessCourierRunner,
181};
182pub use claude_runtime_state::{
183    ClaudeBackgroundChild, ClaudeBackgroundState, ClaudeCronJob, ClaudeQueueState,
184    ClaudeRuntimeManifest, ClaudeRuntimePosture, ClaudeRuntimeResidue, ClaudeWakeup,
185    CLAUDE_RUNTIME_MANIFEST_VERSION,
186};
187pub use config::{
188    project_root_for, ApprovalPolicy, CachePlan, Config, ConfigBuilder, ConfigFile, ConfigProfile,
189    ContextInjectionBlock, HookDecision, LifecycleEvent, LifecycleHook, PreToolOutcome,
190    SteeringMode, StopGateHook, ToolAdvertising, ToolOverride, ToolOverrideProfile,
191    DEFAULT_SYSTEM_PROMPT,
192};
193pub use configfile::HarnessConfig;
194pub use interop_settings::{
195    configure_harness_interop_settings, inspect_harness_interop_settings, HarnessAdvisorySeverity,
196    HarnessInteropAdvisory, HarnessInteropControl, HarnessInteropSettingsError,
197    HarnessInteropSettingsReport, HarnessSettingChange, HarnessSettingChoice,
198    HarnessSettingRecommendation, HarnessSettingScope, CLAUDE_CROSS_SESSION_INBOUND_KEY,
199    HARNESS_INTEROP_SETTINGS_SCHEMA,
200};
201pub use jobs::{
202    get_job, list_jobs, supports_jobs, JobDeliver, JobPayload, JobSchedule, JobScope, JobSource,
203    JobsListing, JobsQuery, ScheduledJob, CLAUDE_SESSION_SCAN_LIMIT, JOB_HARNESSES,
204};
205pub use jobs_control::{
206    harness_program, mutate, supports_job_control, JobControlError, JobDeliverSpec, JobMutation,
207    JobMutationOutcome, JobPayloadSpec, JobScheduleSpec, JobVerb, CONTROLLED_JOB_HARNESSES,
208};
209pub use live_runtime::{
210    discover_live_runtime, find_live_runtime, forget_live_runtime, list_live_runtimes,
211    register_live_runtime, register_live_runtime_with_metadata, resolve_live_runtime,
212    LiveRuntimeEndpoint, LiveRuntimeMetadata, LiveRuntimeReceiptError, LiveRuntimeRecord,
213    LiveRuntimeRegistration, LiveRuntimeSource, LiveRuntimeSupervisor, ResolvedLiveRuntime,
214};
215pub use memory::{
216    search_memory, show_memory, supports_memory, MemoryDocument, MemoryError, MemoryMatch,
217    MemoryQuery, MemoryScope, MemorySearchQuery, MEMORY_HARNESSES, MEMORY_SCHEMA,
218};
219pub use modules::{ModuleActivation, ModuleId};
220pub use orchestrator::{
221    clear_lease, daemon_entry, install_service, live_lease, lock_path, read_lease, service_status,
222    service_unit, uninstall_service, write_lease, write_unit, Lease, OrchestratorError,
223    ServiceState, ServiceUnit, DAEMON_ENTRY, LOCK_FILE, SERVICE_DIR, SERVICE_NAME,
224};
225pub use orchestrator_door::{
226    daemon_is_live, socket_path, Door, DoorAnswer, DoorError, NODE_BIN_ENV, SOCKET_FILE,
227};
228pub use profiles::{
229    get_profile, list_profiles, ProfileError, ProfileKind, ProfileRow, HERMES_DEFAULT_PROFILE,
230    PROFILES_SCHEMA, PROFILE_HARNESSES,
231};
232pub use profiles_control::{
233    supports_profile_control, ProfileControlError, ProfileMutation, ProfileMutationOutcome,
234    ProfileVerb, CONTROLLED_PROFILE_HARNESSES,
235};
236pub use routes::{list_routes, RouteError, RouteMatch, RouteRow, ROUTES_SCHEMA, ROUTE_HARNESSES};
237pub use runs::{
238    get_run, list_runs, supports_runs, HarnessRun, RunDelivery, RunSource, RunsListing, RunsQuery,
239    RUN_HARNESSES,
240};
241pub use sessions_control::{
242    controlled_verbs, supports_session_control, SessionControlError, SessionDoor, SessionMutation,
243    SessionMutationOutcome, SessionVerb, CONTROLLED_SESSION_HARNESSES,
244};
245pub use triggers::{
246    list_triggers, TriggerError, TriggerKind, TriggerRow, TRIGGERS_SCHEMA, TRIGGER_HARNESSES,
247};
248
249/// Format an agent's final reply for output. `json` wraps it as
250/// `{"result": "..."}`; otherwise the reply is returned as-is. The
251/// stream-json form is the live [`AgentEvent`] stream via an [`EventSink`].
252pub fn format_reply(reply: &str, json: bool) -> String {
253    if json {
254        serde_json::json!({ "result": reply }).to_string()
255    } else {
256        reply.to_string()
257    }
258}
259pub use error::{Error, Result};
260pub use event::{AgentEvent, EventSink};
261pub use fidelity::{
262    core_messages, measure_fidelity, messages_equal, messages_equal_multimodal, replay_eligible,
263    Fidelity, FidelityMetric, FidelityResidue,
264};
265#[cfg(feature = "adapter-api")]
266pub use frontend::HttpFrontendRuntime;
267pub use frontend::{
268    FrontendActions, FrontendApprovalDecision, FrontendAttachSnapshot, FrontendAttachment,
269    FrontendCommandDescriptor, FrontendConnectionState, FrontendDisplayCapabilities,
270    FrontendElicitationAction, FrontendEvent, FrontendOperationDescriptor,
271    FrontendOperationInvocation, FrontendOperationKind, FrontendOperationResult, FrontendRequest,
272    FrontendRequestKind, FrontendResponse, FrontendRuntime, FrontendRuntimeDescriptor,
273    FrontendRuntimeError, FrontendRuntimeMetadata, FrontendTurnState, FRONTEND_REPLAY_CAPACITY,
274    FRONTEND_RUNTIME_SCHEMA_VERSION,
275};
276pub use frontend_contract_generated::{
277    FrontendFacadeMethod, FrontendFacadeTransport, GeneratedFrontendClient,
278};
279pub use harness_auth::{
280    harness_authentication_methods, harness_authentication_plan, inspect_harness_authentication,
281    HarnessAuthenticationEnvironment, HarnessAuthenticationError, HarnessAuthenticationInteraction,
282    HarnessAuthenticationLaunch, HarnessAuthenticationMethod, HarnessAuthenticationMethodId,
283    HarnessAuthenticationPlan, HarnessAuthenticationReport, HarnessAuthenticationState,
284    HarnessBrowserBehavior, HARNESS_AUTHENTICATION_SCHEMA,
285};
286pub use harness_service::{
287    HarnessSessionService, HARNESS_SERVICE_VERSION, RUNTIME_EVENT_METHOD,
288    SESSION_ACTIVITY_EVENT_METHOD, SESSION_EVENT_METHOD, SESSION_INDEX_EVENT_METHOD,
289};
290pub use message::{
291    is_tool_error, mark_tool_error, mark_tool_outcome_unknown, tool_outcome, ChatMessage,
292    FunctionCall, Role, ToolCall, ToolOutcome, TOOL_ERROR_METADATA_KEY,
293    TOOL_OUTCOME_UNKNOWN_METADATA_KEY,
294};
295pub use provider::{
296    model_context_limit, ChatRequest, OpenAiProvider, PromptTokensDetails, Provider, RetryLog,
297    RetryNotice, ToolSchema, Usage, SERVED_MODEL_KEY, UNKNOWN_MODEL_CONTEXT_FLOOR,
298};
299#[cfg(feature = "adapter-api")]
300pub use runtime::SupercodeHttpRuntimeBackend;
301pub use runtime::{
302    AcpRuntimeBackend, BearerToken, ClaudeCodeRuntimeBackend, CodexRuntimeBackend, HarnessEvent,
303    McpServerLaunch, OpenCodeRuntimeBackend, PiRuntimeBackend, ResolvedRuntimeConnection,
304    RuntimeAttachRequest, RuntimeBackend, RuntimeCapabilities, RuntimeConnectLaunch,
305    RuntimeConnection, RuntimeEndpoint, RuntimeHandle, RuntimeInput, RuntimeLaunch,
306    RuntimeStartRequest,
307};
308pub use runtime_lease::{
309    CoordinatedRuntime, CoordinatedRuntimeClient, RuntimeAuthorization, RuntimeClientId,
310    RuntimeControllerLease, RuntimeLeaseCoordinator, RuntimeLeaseError, RuntimeLeaseSnapshot,
311    RuntimeObserverLease, RuntimePermission, DEFAULT_RUNTIME_LEASE_TTL_MS,
312};
313#[cfg(feature = "adapter-api")]
314pub use runtime_registry::{
315    LocalRuntimeRegistry, RuntimeRegistryEntry, RuntimeRegistryEvent, RuntimeRegistryOwner,
316    RuntimeRegistryQuery, RuntimeRegistryState, RuntimeRegistryWatch,
317};
318pub use sandbox::{landlock_available, netns_available, SandboxEnvPolicy, SandboxEscalation};
319pub use sdk::{
320    create_agent, discover_session_page, discover_sessions, load_session, load_session_path,
321    resume_agent, show_model_input, submit_agent, submit_agent_with_images, RuntimeSubmitError,
322    SdkAgent, SdkCapabilities, SdkError, SdkErrorCode, SdkEvent, SdkOperation, SdkPromptSource,
323    SdkRequest, SdkRuntime, SdkRuntimeEvent, SdkService, SDK_SCHEMA_VERSION,
324};
325pub use server::RpcEngine;
326pub use session::{
327    CrossSurface, OrchestrationNouns, Recurrence, Session, SessionFormat, SessionMeta,
328    SessionSource, SurfaceKey, Trigger, WorkspaceKind, WorkspaceRef,
329};
330pub use session_activity::{
331    SessionActivity, SessionActivityEvidence, SessionPresence, SessionTurnState,
332};
333pub use session_index::{SessionIndexChange, SessionIndexDelta, SessionIndexKey};
334pub use skills::{
335    declared_skill_name, list_skills, skill_roots, writable_skill_roots, SkillHomes, SkillRow,
336    SkillScope, SkillsQuery, SKILL_HARNESSES,
337};
338pub use skills_control::{
339    mutate_skill, supports_skill_control, SkillControlError, SkillMutation, SkillMutationOutcome,
340    SkillVerb, CONTROLLED_SKILL_HARNESSES,
341};
342pub use store::{SessionInfo, SessionStore};
343pub use support::{
344    harness_support, harness_support_registry, HarnessSupportDescriptor, ImplementationKind,
345    NativeSupport, RuntimeSupport, SupportRegistryReport, SUPPORT_REGISTRY_SCHEMA,
346};
347pub use tools::{
348    shell_sandbox_unenforceable, SandboxPolicy, SchemaTier, Tool, ToolContext, ToolRegistry,
349    WriteObserver,
350};
351pub use watch::{SessionFollower, SessionSnapshotReason, SessionWatchEvent};
supercode_harness/lib.rs

supercode_harness/
lib.rs
