Expand description
§Volter Harness
A lightweight, fully-customizable AI coding-agent SDK in Rust.
supercode is a native agent loop — it talks directly to any model through
OpenRouter (or any other OpenAI-compatible endpoint),
drives a configurable set of tools, and is designed to be a superset of what
tools like Claude Code and Codex can do: every prompt, every tool description,
and every tool’s on/off state is yours to control.
§Quick start
use supercode_harness::{Agent, Config};
// Reads OPENROUTER_API_KEY from the environment by default.
let config = Config::builder()
.model("anthropic/claude-opus-4-8")
.system_prompt("You are a terse, expert pair programmer.")
.build();
let mut agent = Agent::new(config)?;
let reply = agent.send("List the files in the current directory.").await?;
println!("{reply}");§Design
Config— the single knob box: model, endpoint, credentials, sampling, the system prompt, and per-tool overrides (enable/disable + custom descriptions).Provider— the model transport.OpenAiProviderspeaks the OpenAI chat-completions wire format and defaults to OpenRouter, so it reaches Claude, GPT, Gemini, Llama, and anything else OpenRouter exposes.Tool/ToolRegistry— the capability surface. Built-ins cover file read/write/edit, directory listing, glob, content search, and shell execution. Register your own to extend it.Agent— the loop that ties it together: it streams a turn, runs any tool calls the model requests, feeds results back, and repeats until the model produces a final answer.
Re-exports§
pub use acp_frontend::AcpFrontendCheckpoint;pub use acp_frontend::AcpFrontendConnectOptions;pub use acp_frontend::AcpFrontendRuntime;pub use approvals::approval_harnesses;pub use approvals::lists_approvals;pub use approvals::plan_reply;pub use approvals::ApprovalChoice;pub use approvals::ApprovalDecision;pub use approvals::ApprovalDoor;pub use approvals::ApprovalKind;pub use approvals::ApprovalOption;pub use approvals::ApprovalRegistry;pub use approvals::ApprovalResolution;pub use approvals::ApprovalResolveError;pub use approvals::ApprovalRow;pub use approvals::ApprovalStatus;pub use approvals::ApprovalsQuery;pub use approvals::ApprovalsResolveParams;pub use channels::channel_status;pub use channels::list_channels;pub use channels::ChannelError;pub use channels::ChannelRow;pub use channels::ChannelStatus;pub use channels::CHANNELS_SCHEMA;pub use channels::CHANNEL_HARNESSES;pub use claude_peer::read_claude_peer_settings;pub use claude_peer::read_registry as read_claude_peer_registry;pub use claude_peer::resolve_live_session;pub use claude_peer::update_claude_peer_settings;pub use claude_peer::user_settings_path as claude_user_settings_path;pub use claude_peer::write_claude_peer_settings;pub use claude_peer::ClaudeCrossSessionInbound;pub use claude_peer::ClaudePeerRefusal;pub use claude_peer::ClaudePeerRefusalError;pub use claude_peer::ClaudePeerSession;pub use claude_peer::ClaudePeerSettings;pub use claude_peer::ClaudePeerSettingsError;pub use claude_peer::ClaudePeerStatus;pub use claude_runtime_state::ClaudeBackgroundChild;pub use claude_runtime_state::ClaudeBackgroundState;pub use claude_runtime_state::ClaudeCronJob;pub use claude_runtime_state::ClaudeQueueState;pub use claude_runtime_state::ClaudeRuntimeManifest;pub use claude_runtime_state::ClaudeRuntimePosture;pub use claude_runtime_state::ClaudeRuntimeResidue;pub use claude_runtime_state::ClaudeWakeup;pub use claude_runtime_state::CLAUDE_RUNTIME_MANIFEST_VERSION;pub use configfile::HarnessConfig;pub use interop_settings::configure_harness_interop_settings;pub use interop_settings::inspect_harness_interop_settings;pub use interop_settings::HarnessAdvisorySeverity;pub use interop_settings::HarnessInteropAdvisory;pub use interop_settings::HarnessInteropControl;pub use interop_settings::HarnessInteropSettingsError;pub use interop_settings::HarnessInteropSettingsReport;pub use interop_settings::HarnessSettingChange;pub use interop_settings::HarnessSettingChoice;pub use interop_settings::HarnessSettingRecommendation;pub use interop_settings::HarnessSettingScope;pub use interop_settings::CLAUDE_CROSS_SESSION_INBOUND_KEY;pub use interop_settings::HARNESS_INTEROP_SETTINGS_SCHEMA;pub use jobs::get_job;pub use jobs::list_jobs;pub use jobs::supports_jobs;pub use jobs::JobDeliver;pub use jobs::JobPayload;pub use jobs::JobSchedule;pub use jobs::JobScope;pub use jobs::JobSource;pub use jobs::JobsListing;pub use jobs::JobsQuery;pub use jobs::ScheduledJob;pub use jobs::CLAUDE_SESSION_SCAN_LIMIT;pub use jobs::JOB_HARNESSES;pub use jobs_control::harness_program;pub use jobs_control::mutate;pub use jobs_control::supports_job_control;pub use jobs_control::JobControlError;pub use jobs_control::JobDeliverSpec;pub use jobs_control::JobMutation;pub use jobs_control::JobMutationOutcome;pub use jobs_control::JobPayloadSpec;pub use jobs_control::JobScheduleSpec;pub use jobs_control::JobVerb;pub use jobs_control::CONTROLLED_JOB_HARNESSES;pub use jobs_notepad::JobNotepad;pub use jobs_notepad::JobNotepadEntry;pub use jobs_notepad::JobNotepadRequest;pub use live_runtime::discover_live_runtime;pub use live_runtime::find_live_runtime;pub use live_runtime::forget_live_runtime;pub use live_runtime::list_live_runtimes;pub use live_runtime::register_live_runtime;pub use live_runtime::register_live_runtime_with_metadata;pub use live_runtime::resolve_live_runtime;pub use live_runtime::LiveRuntimeEndpoint;pub use live_runtime::LiveRuntimeMetadata;pub use live_runtime::LiveRuntimeReceiptError;pub use live_runtime::LiveRuntimeRecord;pub use live_runtime::LiveRuntimeRegistration;pub use live_runtime::LiveRuntimeSource;pub use live_runtime::LiveRuntimeSupervisor;pub use live_runtime::ResolvedLiveRuntime;pub use memory::search_memory;pub use memory::show_memory;pub use memory::supports_memory;pub use memory::MemoryDocument;pub use memory::MemoryError;pub use memory::MemoryMatch;pub use memory::MemoryQuery;pub use memory::MemoryScope;pub use memory::MemorySearchQuery;pub use memory::MEMORY_HARNESSES;pub use memory::MEMORY_SCHEMA;pub use modules::ModuleActivation;pub use modules::ModuleId;pub use orchestrator::clear_lease;pub use orchestrator::daemon_entry;pub use orchestrator::install_service;pub use orchestrator::live_lease;pub use orchestrator::lock_path;pub use orchestrator::read_lease;pub use orchestrator::service_status;pub use orchestrator::service_unit;pub use orchestrator::uninstall_service;pub use orchestrator::write_lease;pub use orchestrator::write_unit;pub use orchestrator::Lease;pub use orchestrator::OrchestratorError;pub use orchestrator::ServiceState;pub use orchestrator::ServiceUnit;pub use orchestrator::DAEMON_ENTRY;pub use orchestrator::LOCK_FILE;pub use orchestrator::SERVICE_DIR;pub use orchestrator::SERVICE_NAME;pub use orchestrator_door::daemon_is_live;pub use orchestrator_door::socket_path;pub use orchestrator_door::Door;pub use orchestrator_door::DoorAnswer;pub use orchestrator_door::DoorError;pub use orchestrator_door::NODE_BIN_ENV;pub use orchestrator_door::SOCKET_FILE;pub use profiles::get_profile;pub use profiles::list_profiles;pub use profiles::ProfileError;pub use profiles::ProfileKind;pub use profiles::ProfileRow;pub use profiles::HERMES_DEFAULT_PROFILE;pub use profiles::PROFILES_SCHEMA;pub use profiles::PROFILE_HARNESSES;pub use profiles_control::supports_profile_control;pub use profiles_control::ProfileControlError;pub use profiles_control::ProfileMutation;pub use profiles_control::ProfileMutationOutcome;pub use profiles_control::ProfileVerb;pub use profiles_control::CONTROLLED_PROFILE_HARNESSES;pub use routes::list_routes;pub use routes::RouteError;pub use routes::RouteMatch;pub use routes::RouteRow;pub use routes::ROUTES_SCHEMA;pub use routes::ROUTE_HARNESSES;pub use runs::get_run;pub use runs::list_runs;pub use runs::supports_runs;pub use runs::HarnessRun;pub use runs::RunDelivery;pub use runs::RunSource;pub use runs::RunsListing;pub use runs::RunsQuery;pub use runs::RUN_HARNESSES;pub use sessions_control::controlled_verbs;pub use sessions_control::supports_session_control;pub use sessions_control::SessionControlError;pub use sessions_control::SessionDoor;pub use sessions_control::SessionMutation;pub use sessions_control::SessionMutationOutcome;pub use sessions_control::SessionVerb;pub use sessions_control::CONTROLLED_SESSION_HARNESSES;pub use teams::connector_service_name as teams_connector_service_name;pub use teams::connector_service_status as teams_connector_service_status;pub use teams::connector_service_unit as teams_connector_service_unit;pub use teams::install_connector_service as install_teams_connector_service;pub use teams::install_service as install_teams_service;pub use teams::service_status as teams_service_status;pub use teams::service_unit as teams_service_unit;pub use teams::teams_entry;pub use teams::teams_home;pub use teams::uninstall_connector_service as uninstall_teams_connector_service;pub use teams::uninstall_service as uninstall_teams_service;pub use teams::write_unit as write_teams_unit;pub use teams::TeamsError;pub use teams::SERVICE_DIR as TEAMS_SERVICE_DIR;pub use teams::SERVICE_NAME as TEAMS_SERVICE_NAME;pub use teams::TEAMS_ENTRY;pub use triggers::list_triggers;pub use triggers::TriggerError;pub use triggers::TriggerKind;pub use triggers::TriggerRow;pub use triggers::TRIGGERS_SCHEMA;pub use triggers::TRIGGER_HARNESSES;pub use frontend::HttpFrontendRuntime;pub use frontend::FrontendActions;pub use frontend::FrontendApprovalDecision;pub use frontend::FrontendAttachSnapshot;pub use frontend::FrontendAttachment;pub use frontend::FrontendCommandDescriptor;pub use frontend::FrontendConnectionState;pub use frontend::FrontendDisplayCapabilities;pub use frontend::FrontendElicitationAction;pub use frontend::FrontendEvent;pub use frontend::FrontendOperationDescriptor;pub use frontend::FrontendOperationInvocation;pub use frontend::FrontendOperationKind;pub use frontend::FrontendOperationResult;pub use frontend::FrontendRequest;pub use frontend::FrontendRequestKind;pub use frontend::FrontendResponse;pub use frontend::FrontendRuntime;pub use frontend::FrontendRuntimeDescriptor;pub use frontend::FrontendRuntimeError;pub use frontend::FrontendRuntimeMetadata;pub use frontend::FrontendTurnState;pub use frontend::FRONTEND_REPLAY_CAPACITY;pub use frontend::FRONTEND_RUNTIME_SCHEMA_VERSION;pub use harness_auth::harness_authentication_methods;pub use harness_auth::harness_authentication_plan;pub use harness_auth::inspect_harness_authentication;pub use harness_auth::HarnessAuthenticationEnvironment;pub use harness_auth::HarnessAuthenticationError;pub use harness_auth::HarnessAuthenticationInteraction;pub use harness_auth::HarnessAuthenticationLaunch;pub use harness_auth::HarnessAuthenticationMethod;pub use harness_auth::HarnessAuthenticationMethodId;pub use harness_auth::HarnessAuthenticationPlan;pub use harness_auth::HarnessAuthenticationReport;pub use harness_auth::HarnessAuthenticationState;pub use harness_auth::HarnessBrowserBehavior;pub use harness_auth::HARNESS_AUTHENTICATION_SCHEMA;pub use harness_service::DetachedAnswer;pub use harness_service::DetachedCall;pub use harness_service::HarnessSessionService;pub use harness_service::OpenedRuntime;pub use harness_service::ReturnedRuntime;pub use harness_service::RuntimeOpen;pub use harness_service::DETACHED_CALL_DEADLINE;pub use harness_service::DETACHED_METHODS;pub use harness_service::HARNESS_SERVICE_VERSION;pub use harness_service::RUNTIME_CONTROL_DEADLINE;pub use harness_service::RUNTIME_EVENT_METHOD;pub use harness_service::RUNTIME_OPEN_DEADLINE;pub use harness_service::RUNTIME_OPEN_METHODS;pub use harness_service::SESSION_ACTIVITY_EVENT_METHOD;pub use harness_service::SESSION_DISCOVER_DEADLINE;pub use harness_service::SESSION_EVENT_METHOD;pub use harness_service::SESSION_INDEX_EVENT_METHOD;pub use runtime::SupercodeHttpRuntimeBackend;pub use runtime::AcpRuntimeBackend;pub use runtime::BearerToken;pub use runtime::ClaudeCodeRuntimeBackend;pub use runtime::CodexRuntimeBackend;pub use runtime::HarnessEvent;pub use runtime::McpServerLaunch;pub use runtime::OpenCodeRuntimeBackend;pub use runtime::PiRuntimeBackend;pub use runtime::ResolvedRuntimeConnection;pub use runtime::RuntimeAttachRequest;pub use runtime::RuntimeBackend;pub use runtime::RuntimeCapabilities;pub use runtime::RuntimeConnectLaunch;pub use runtime::RuntimeConnection;pub use runtime::RuntimeEndpoint;pub use runtime::RuntimeHandle;pub use runtime::RuntimeInput;pub use runtime::RuntimeLaunch;pub use runtime::RuntimeStartRequest;pub use runtime_lease::CoordinatedRuntime;pub use runtime_lease::CoordinatedRuntimeClient;pub use runtime_lease::RuntimeAuthorization;pub use runtime_lease::RuntimeClientId;pub use runtime_lease::RuntimeControllerLease;pub use runtime_lease::RuntimeLeaseCoordinator;pub use runtime_lease::RuntimeLeaseError;pub use runtime_lease::RuntimeLeaseSnapshot;pub use runtime_lease::RuntimeObserverLease;pub use runtime_lease::RuntimePermission;pub use runtime_lease::DEFAULT_RUNTIME_LEASE_TTL_MS;pub use runtime_registry::LocalRuntimeRegistry;pub use runtime_registry::RuntimeRegistryEntry;pub use runtime_registry::RuntimeRegistryEvent;pub use runtime_registry::RuntimeRegistryOwner;pub use runtime_registry::RuntimeRegistryQuery;pub use runtime_registry::RuntimeRegistryState;pub use runtime_registry::RuntimeRegistryWatch;pub use sandbox::landlock_available;pub use sandbox::netns_available;pub use sandbox::SandboxEnvPolicy;pub use sandbox::SandboxEscalation;pub use sdk::create_agent;pub use sdk::discover_session_page;pub use sdk::discover_sessions;pub use sdk::load_session;pub use sdk::load_session_path;pub use sdk::resume_agent;pub use sdk::show_model_input;pub use sdk::submit_agent;pub use sdk::submit_agent_with_images;pub use sdk::RuntimeSubmitError;pub use sdk::SdkAgent;pub use sdk::SdkCapabilities;pub use sdk::SdkError;pub use sdk::SdkErrorCode;pub use sdk::SdkEvent;pub use sdk::SdkOperation;pub use sdk::SdkPromptSource;pub use sdk::SdkRequest;pub use sdk::SdkRuntime;pub use sdk::SdkRuntimeEvent;pub use sdk::SdkService;pub use sdk::SDK_SCHEMA_VERSION;pub use server::RpcEngine;pub use session_activity::SessionActivity;pub use session_activity::SessionActivityEvidence;pub use session_activity::SessionPresence;pub use session_activity::SessionTurnState;pub use session_index::SessionIndexChange;pub use session_index::SessionIndexDelta;pub use session_index::SessionIndexKey;pub use skills::declared_skill_name;pub use skills::list_skills;pub use skills::skill_roots;pub use skills::writable_skill_roots;pub use skills::SkillHomes;pub use skills::SkillRow;pub use skills::SkillScope;pub use skills::SkillsQuery;pub use skills::SKILL_HARNESSES;pub use skills_control::mutate_skill;pub use skills_control::supports_skill_control;pub use skills_control::SkillControlError;pub use skills_control::SkillMutation;pub use skills_control::SkillMutationOutcome;pub use skills_control::SkillVerb;pub use skills_control::CONTROLLED_SKILL_HARNESSES;pub use store::SessionInfo;pub use store::SessionStore;pub use support::harness_support;pub use support::harness_support_registry;pub use support::HarnessSupportDescriptor;pub use support::ImplementationKind;pub use support::NativeSupport;pub use support::RuntimeSupport;pub use support::SupportRegistryReport;pub use support::SUPPORT_REGISTRY_SCHEMA;pub use tools::shell_sandbox_unenforceable;pub use tools::SandboxPolicy;pub use tools::SchemaTier;pub use tools::Tool;pub use tools::ToolContext;pub use tools::ToolRegistry;pub use tools::WriteObserver;
Modules§
- acp_
frontend - First-class ACP client implementation of the canonical SDK runtime.
- acp_
server - Inbound Agent Client Protocol adapter for the SDK-owned Supercode runtime.
- agent_
package - Repository-native agent packages.
- approvals
- ORCH-9 (observed tier): one uniform listing of the approval requests waiting for an answer, across every harness supercode drives.
- audit
- Corpus coverage audit.
- channels
- ORCH-14 — the
channelnoun at the OBSERVED tier: one uniform row per transport + account a gateway harness is reachable on, read from the harness’s own config file and never written. - checkpoint
- §2 module 20
checkpoint(COMPOSABLE-HARNESS-DESIGN.md line 470): file checkpointing / shadow-git; D4-adjacent revert; D3 turn-diff tracking. Line 1504: “restores FILES, not context — pairs with, never replaces, the reduction sidecar.” - claude_
compat - Claude Code project compatibility helpers.
- claude_
peer - Live Claude Code peer sessions: registry discovery and inbound policy.
- claude_
relay - Claude relays: the degraded tier’s door into a Claude Code session that supercode does not control.
- claude_
runtime_ state - Lossless, non-executing reconstruction of Claude Code runtime state.
- codex_
peer - Live stock-Codex session discovery.
- config_
schema - BP-9 (D6 row “Published JSON schema for config”, cc§6): the published
JSON Schema for the supercode config file —
.supercode.toml,~/.config/supercode/config.toml, and the JSON mirror (HarnessConfig::from_json_str). - configfile
- §3 “The Single Config File” (
docs/composable-harness/COMPOSABLE-HARNESS-DESIGN.md) — P1 of the composable-harness migration (design §5.2, phase P1). - context_
injection - BP-4 (catalog:91 “Synthetic context-injection blocks”, design §1.4:
“harness-spliced reminders/nudges … the ambient nudge class is core”):
the injection REGISTRY behind
core.context_injections. - formatters
- §2 module 29
formatters(COMPOSABLE-HARNESS-DESIGN.md line 479): “D10/oc§10 format-on-write” — reuses the EXACTcrate::tools::WriteObserverseam P5-9 built forcheckpoint(D-5: “write-path interception seam shared with checkpoint”), rather than a second interception point. - frontend
- Protocol-neutral frontend contract for one SDK-owned Supercode runtime.
- git_
metadata - P4e (COMPOSABLE-HARNESS-DESIGN.md §1.6/§3.1
core.session.git_metadata, catalog:331 “Git integration (metadata, diff, PR)”): a persisted, TYPED record of the git branch/sha/dirty state a session was RUNNING under, captured ONCE at session start (closes the loop catalog:331 flags — supercode already preserves a foreign session’s own git-shaped fields byte-for-byte on IMPORT viaSession::raw’s verbatim capture; this is the WRITE half: supercode’s OWN sessions get the same provenance). Deliberately flat/typed (not a formatted string), the exact same rationale ascrate::usage_log::UsageRecord/crate::model_change::ModelChangeRecord(§1.13): a translatable, lossless session-data channel, not a lossy notice — so it survives a save/load round trip byte-for-byte, and a future reader (a translator,doctor/inspect stats) can consume it without re-parsing prose. - goals
- BP-7 (catalog §4a “Goals (persistent objective across turns)”, cc’s
/goal, cx’s/goal+goals_1.sqlite): the session’s standing objective. - harness_
auth - Native coding-harness authentication coordination.
- harness_
command - The controlled tier’s substrate: one harness command, ready to run and ready to narrate.
- harness_
service - Versioned, language-neutral service over persisted harness sessions.
- hermes_
import - UNI-18: the Hermes write path, through Hermes’s own door.
- human_
export - P4e (COMPOSABLE-HARNESS-DESIGN.md §1.6/§3.1
core.session.export_format, catalog:283 “transcript export for humans”): a READ-ONLY rendering of acrate::Session’s conversation into text a human reads directly (terminal/file/clipboard) or opens in a browser — CC’s/export+/copy, CX’s Ctrl+O copy-last. This is core, not gated by thesession.sharemodule (§1.6: “export-to-human is universal while share links … are the OC+PI-only partsession.shareactually narrows to”). - interop_
settings - Harness-owned controls that materially affect Supercode interoperability.
- jobs
- Observed-tier, READ-ONLY inventory of scheduled jobs across the harnesses that have them (Domain 11, concept 6).
- jobs_
control - Controlled-tier scheduled jobs (Domain 11, concept 6) — the FIRST controlled-tier noun, and the shape the rest of wave 2 copies.
- jobs_
notepad - A job’s notepad: the durable key-value state a scheduled job keeps between
its runs (
docs/architecture/content-spec-status.md: status, written by the agent or an operator through the harness’s own verb, never byapply). - live_
runtime - Trusted local receipts for attachable Supercode runtimes.
- lsp
- §2 module 28
lsp(COMPOSABLE-HARNESS-DESIGN.md line 478): “D1 LSP diagnostics in edit path + query tool” — this module ships the WEAKEST FORM that satisfies D1: server LIFECYCLE for a HANDFUL of user-configured language servers, and diagnostics surfaced in the edit/write TOOL RESULT via the shared D-5 write-path seam (crate::tools::WriteObserver, P5-9/P5-11). - mail_
mcp - Messaging as tools: the three an agent needs to reach any session, served
over MCP by
supercode message mcp(whichsupercode teams connect --installregisters with each harness at user scope). - mail_
route - One route for every message: which door reaches a receiver, and delivery through it.
- mail_
send - One send for every sender:
supercode message send, the native agent’ssend_message, and a request arriving through another machine’s mail door. It resolves the receiver, routes to another machine through Teams or to the router’s door here, guards against loops and repeats, and words the outcome for the sending agent. - mail_
watch - Idle notices for every harness, from session activity.
- mailbox
- Cross-session mailbox: one Maildir per session address.
- mcp
- P5-2 (COMPOSABLE-HARNESS-DESIGN.md §2 module 15
mcp.client, D7 rows 1-8): full Model Context Protocol client support — stdio (P5-1 baseline, GROWN not rewritten), remote HTTP/SSE transports, resources + templates, prompts-as-commands, server instructions, and elicitation — plus thehandle_request/serve_stdioharness-as-MCP-server direction (module 16). - mcp_
oauth - P5-2 (COMPOSABLE-HARNESS-DESIGN.md §2 module 15 D7 row 2 “OAuth”; §2.1
dep “
model.oauth→ trust-grade token storage” — the same security class applies here): OAuth PROTOCOL support for authenticated remote MCP servers. - memory
- ORCH-12 — the
memorynoun at the OBSERVED tier: read and search the persistent cross-session memory documents a harness keeps on disk. - model_
catalog - §2 module 26
model.catalog(docs/composable-harness/ COMPOSABLE-HARNESS-DESIGN.md§3.1[capabilities.model_catalog]) — P4 of the composable-harness migration (design §5.2 phase P4: “aliases + fallback chains (userconfig.rs:386-411) promoted into core” + thesmall_modelknob). - model_
change - P4c (COMPOSABLE-HARNESS-DESIGN.md §5.2 “P4” core NEW-significant item,
§1.10/§3.1
core.model_switch.allow_switch, D9 row): a persisted, TYPED record of a mid-session model switch — pi’smodel_changeprecedent (design §1.10: “persisted change records … pi’smodel_changeis the cleanest precedent”). Deliberately flat/typed (not a formatted string), mirroringcrate::usage_log::UsageRecord’s exact rationale: a translatable, lossless session-data channel (§1.13), not a lossy notice — so it survives a save/load round trip byte-for-byte in the fields that matter, and a future reader (a translator emitting this same session under another harness’s format, adoctor/inspect statscommand) can consume it without re-parsing prose. - modules
- §2 “The Bolt-on Capability Taxonomy” (
docs/composable-harness/ COMPOSABLE-HARNESS-DESIGN.md) — P3 of the composable-harness migration (design §5.2, phase P3: “AModuleIdenum (the 35 names) + resolved activation set onConfig”). - ontology
- The supercode ontology (
docs/ONTOLOGY.md): the one model under sessions and the orchestration. The supercode ontology (docs/ONTOLOGY.md): the one model under the session spine and the orchestration. Lower layers never import upper ones — this module depends on nothing above it except the session layer’scrate::session::OrchestrationNounswire block, which aBindingprojects onto. - orchestration
- The orchestration piece of the ontology: a harness’s operational home as one typed value.
The orchestration piece of the ontology (
docs/ONTOLOGY.md§2.7,docs/ORCHESTRATOR-IR.md§2): a harness’s operational home as ONE typed value. These are the records the orchestrator loads, steps and saves; a Hermes or OpenClaw home compiles into them and decompiles back (the codecs are ONT-3’s). The wire form is the orchestrator IR’s canonical JSON: the runtime half is never persisted and is not here. - orchestration_
doors - ONT-4: the orchestration doors, in one implementation.
- orchestrator
- The orchestrator’s home, its daemon lease, and the service unit the operator verbs print (ORC-7).
- orchestrator_
door - ORC-13 — the orchestrator’s WRITE door, the one every controlled-tier noun
goes through when
--harness orchestratornames it. - output_
style - BP-5 (catalog D2 “Output style / personality module”: swappable response-style instruction layer; cc§7 “Output styles”; cx§2 “Personality layer”) — the named response-style layer.
- parity
- Behavior-parity ledger: the product’s own gap count, for the
cc-parityandcx-paritypresets and for the orchestration harnesses. - path_
rules - BP-5 (catalog D2 “Path-scoped rules”: rule files activated only when
matching files are touched; cc§2 “
.claude/rules/*.md— modular instruction files; optionalpaths:frontmatter scopes a rule to file globs so it loads only when Claude touches matching files”). - permissions
- P5-1 (COMPOSABLE-HARNESS-DESIGN.md §2 modules 10-11, §2.1 D-3, §2.2 C5, §5.3 risk 1): the permissions engine — command canonicalization + rule algebra + approval policy/cache + oc/cx import translators.
- plugins
- P5-12 (COMPOSABLE-HARNESS-DESIGN.md §2 module 18
plugins, D7 “in-process extension API, packaging/marketplaces, custom tools from files, provider injection, extension UI, plugin/package installation”; §2.1 D-10: “config-borne code execution without a trust gate is an injection hole”). - presets
- §4 “Presets” (
docs/composable-harness/COMPOSABLE-HARNESS-DESIGN.md) — P2 of the composable-harness migration (design §5.2, phase P2). - pricing
- BP-7 (catalog §4a “Turn/budget caps” — the spend cap; “Per-turn cost/usage accounting” — the cost half): token→dollars on the request path.
- pricing_
ref - Reference pricing constants used only to translate measured byte/token savings into a dollar figure in test logs and docs (D15). These are stated constants for one Opus-class API list price (July 2026) — not a live lookup, and not used anywhere on the request path.
- profiles
- ORCH-10 — the
profilenoun at the OBSERVED tier: one uniform row for every named, routable config home supercode can see, read from each harness’s own files and never written. - profiles_
control - ORCH-21 — the
profilenoun at the CONTROLLED tier: create and delete a routed config home through the HARNESS’S OWN verb, with supercode as the uniform client. - reduce
- Reversible reduction for supercode sessions: the reducer package, plus the adapter that exports, projects and inverts a stored session through it.
- relay_
endpoint - The Messages API a Claude relay talks to: deterministic, no model.
- routes
- ORCH-15 (observed tier): the routing noun — which profile / agent a surface tuple resolves to.
- runs
- Observed-tier, READ-ONLY inventory of scheduled-job FIRES across the harnesses that keep a run store (Domain 11, concept 7).
- runtime
- Primitive live-runtime contracts and the Codex app-server reference adapter.
- runtime_
lease - Transport-neutral observer and controller leases for live SDK runtimes.
- runtime_
mail - The default delivery tier of the mailbox: sessions supercode controls.
- runtime_
registry - Authenticated inventory and attachment for live and persisted sessions.
- sandbox
- P5-10 (COMPOSABLE-HARNESS-DESIGN.md §2 module 12
permissions.sandbox, ~row 462): the OS-level enforcement BACKSTOPpermissions.rules’ rule-layer floor and the file-toolcrate::tools::SandboxPolicyboth defer to for full coverage (crate::permissionsmodule doc: “complete OS-level write confinement of arbitrary bash… iscapabilities. permissions.sandbox’s job (P5 module 10, a later unit), not this one’s” — this IS that unit). - schema
- Typed schemas for the on-disk session formats.
- sdk
- Versioned public SDK contract shared by every Supercode surface.
- server
- §2 module 31
server(COMPOSABLE-HARNESS-DESIGN.md, D7 “full programmatic RPC/HTTP server”, D8 “remote attach”, D10 “daemon”; §1.9 Obligation 9’s out-of-process half — the in-process SDK already meets the core commitment viacrate::EventSink). - session_
activity - Protocol-neutral activity for persisted and live harness sessions.
- session_
index - Revisioned session-list subscriptions for latency-sensitive frontends.
- session_
journal - BP-8 (catalog domain 5): the append-only session journal — one
flush-per-record log of everything that happens to a session while it is
live, written beside the transcript as
<name>.journal.jsonl. - session_
title - P4b (COMPOSABLE-HARNESS-DESIGN.md §5.2 “P4”, §1.6/§3.1
core.session.auto_title, catalog:150, D-9): auto-title / session summary — a small-model side-call that titles a session, mirroringcrate::reduce::summarize’s plumbing exactly: an injectable trait (real implementations call out to a model; this crate’s own tests only ever inject deterministic fakes — no real network/model call anywhere in this crate, same posture ascrate::reduce::summarize::SpanSummarizer), a fixed versioned prompt, and a “never blocks, never fails the caller” contract. - sessions_
control - Controlled-tier conversations (Domain 11, concept 5) —
new,reset,archive,deleteover one uniform door. - skills
- ORCH-11 (observed tier): read-only enumeration of the skill packages each harness has installed.
- skills_
control - Controlled-tier skills (Domain 11, concept 15) —
installandremove, each through the door the harness itself publishes. - store
- A directory-backed store for supercode’s own sessions — naming, titles,
listing, archiving, and deletion. The analog of
claude --name/ the Codexresume/archive/deletesession lifecycle. - subagents
- P5-3 (COMPOSABLE-HARNESS-DESIGN.md §2 module 9
subagents: “D1 spawn tool; D3 sub-agents/named-defs/background+resume/teams; D5 subagent transcripts”; §2.1 D-1 “subagents → core.session(lineage), core.tools; background-mode → permissions.approvals”; §2.2 C6): the data shapes and pure-function resource-bound checks the spawn/join/background machinery incrate::agent::Agentbuilds on. Kept separate fromagent.rsso the depth/concurrency-cap arithmetic and the lineage record shape are unit-testable without a fullAgent/mock-Providerharness — the same “pure config → set, testable without the loop” precedent P3’scrate::modulesmodule documents for itself. - support
- Canonical implementation inventory for external coding harnesses.
- teams
- Where supercode-teams lives on this box, and the service unit that keeps
its machine daemon up (
docs/plans/teams-server.md§11). - tools
- Tools the agent can call.
- triggers
- ORCH-16 (observed tier): the inbound-trigger noun — an HTTP route or hook mapping that opens a turn when something outside the harness fires.
- trust
- BP-10 (COMPOSABLE-HARNESS-DESIGN.md §2 module 14
trust, catalog row “Project/workspace trust gate”): the workspace-trust DECISION — the prompt, its per-project persistence, and the three surfaces it gates. - tui
- P5-4 (COMPOSABLE-HARNESS-DESIGN.md §2 module 30
tui; §1.9 recorded deviation; §2.1tools.question/permissions.approvals(ask-UI) →tui|server): the full-screen interactive TUI, AND — because §2.1 names it as the interactive surface three EARLIER phases explicitly deferred here — the home for the three handlers that close those deferred chains: - turn_
record - BP-7 (catalog §4a “Turn/step bracketing records”, “Interrupt/abort with
state preserved”, “Auto-retry on transient provider errors”): the
persisted per-round-trip marker log — cc’s
turn_duration/api_retrysystem records and cx’sturn_context/turn_aborted/responses_retryrows, in one typed shape. - usage_
log - P4b (COMPOSABLE-HARNESS-DESIGN.md §5.2 “P4”, §1.6/§3.1, catalog §4a
“Turn/step usage records surfaced per turn”): persisted per-turn
token/usage records.
crate::AgentEvent::Usagealready streams this data live (UX-23); this module makes it DURABLE session data — a typed, serde-round-trippable record, not a lossy display-only channel (§1.13’s lossless/sidecar discipline: this is typed session data, exactly likecrate::reduce::ReductionLog, not a text notice). - workflow_
doors - The workflow layer’s read door:
harness.v1.workflow.load, the same code thesupercode workflow loadverb calls. A harness’s board is read as one typedWorkflowvalue; the board is written only through the harness’s own door (hermes kanban …), never here.
Structs§
- Agent
- Chat
Message - A single message in a conversation.
- Chat
Request - A single model-completion request.
- Config
- Everything that shapes an
crate::Agent: the model and endpoint, the credentials, sampling parameters, the system prompt, and per-tool overrides. - Config
Builder - Fluent builder for
Config. - Config
File - A config file: a set of named profiles (the analog of Codex
-p/--profile). This is the SDK/embedder config surface (JSON, viaConfig::from_profile_file). BP-9 gave the same named-bundle mechanism a launch-time selector on the CLI side:supercode --profile <name>selects a[profiles.<name>]bundle out of the user’s TOMLconfig.toml(userconfig::FileConfig), applied as its own layer between the user layer and the project layer (cx§6’suser → profile → projectorder). - Config
Profile - The serializable subset of a
Configthat can live in a config file. (Callbacks/handlers are code-only and are not represented here.) - Context
Injection Block - P4e (§1.4/§3.1
core.context_injections): one named ambient context block – seeConfig::context_injection_blocks. - Context
Usage - BP-4 (catalog:109 “Context-usage introspection”): the live
context-window accounting
Agent::context_usagereports — cc’s/contextgrid and cx’s/status+get_context_remainingin one shape, over the numbersresume --dry-run’s preflight already computes. - Cross
Surface - Metadata recovered from a session log.
ORCH-3: a conversation moved to another surface (Hermes
handoff_*). - Discovery
Page - One stable newest-first discovery page.
- Discovery
Query - Filters and roots used for one catalog scan.
- Fidelity
Metric - Result of measuring one actual translation cell.
- Fidelity
Residue - Measured residue of one actual export/reload cell.
- Function
Call - The function payload of a
ToolCall. - Generated
Frontend Client - Generated typed Rust client over any facade transport.
- Harness
Catalog - Read-only entry point for discovering, loading, and following persisted harness sessions.
- Harness
Homes - Configurable session roots for the built-in harnesses.
- Harness
Id - Extensible identifier for a coding harness.
- Open
AiProvider - An OpenAI-compatible HTTP provider. The composition layer supplies its endpoint, credentials, and headers from runtime configuration.
- Orchestration
Nouns - ORCH-6: the ORCH-3 conversation nouns as one additive wire block, carried
by
harness.v1.sessions.discover/sessions.loadrows and bycrate::catalog::SessionDescriptor. Every field is optional so an older client sees exactly the shape it already knows. - PreTool
Outcome - BP-10: everything a pre-tool hook can say about one call — a decision, a human-readable reason, and (the rewrite half of the row) REPLACEMENT arguments.
- Prompt
Tokens Details - The cache portion of
Usage::prompt_tokens_details. - Recurrence
- Metadata recovered from a session log. ORCH-3: the job a recurring session belongs to.
- Retry
Log - A shared, drainable buffer of
RetryNotices. - Retry
Notice - BP-7 (catalog §4a “Auto-retry on transient provider errors”): one transient failure the transport retried.
- Session
- A normalized, replayable conversation loaded from a tool’s session log.
- Session
Descriptor - Lightweight metadata returned by catalog discovery.
- Session
Follower - Poll-based follower for one persisted Claude Code, Codex, Pi, OpenCode, or Grok session.
- Session
Locator - Stable identity for a persisted harness session.
- Session
Meta - Surface
Key - Metadata recovered from a session log.
ORCH-3: the conversation identity on a surface. Full tuple on a channel;
degenerate (all
None) on a terminal. - Tool
Call - A request from the model to invoke a tool.
- Tool
Override - Per-tool customization: enable/disable a tool and/or override the description the model sees for it.
- Tool
Override Profile - A single tool’s file-settable overrides — the
ConfigProfilemirror ofToolOverride(COMPOSABLE-HARNESS-DESIGN.md §3.1[core.tools.<name>], §3.2 mapping rowcore.tools.enabled+[core.tools.<n>].*). - Tool
Schema - A tool advertised to a model.
- Usage
- Token accounting returned with a completion.
- Workspace
Ref - Metadata recovered from a session log.
ORCH-6: the wire form of [
SessionMeta::workspace] — a typed workspace carried on a discovered or loaded row. The D2 precedence that produces it lives inworkspace()(ORCH-3’s contract); this only names the result.
Enums§
- Agent
Event - Streaming events emitted by a native runtime agent as a turn unfolds.
- Approval
Policy - When the agent must seek approval before running a tool — the analog of
Codex’s
-a untrusted|on-request|neverand Claude’s permission modes. - Cache
Plan - Prompt-caching plan applied while building a provider request.
- Error
- Errors that can arise while configuring or running an
crate::Agent. - Fidelity
- How faithfully a reconstruction reproduces its source.
- Frontend
Facade Method - One method in the versioned language-neutral frontend facade.
- Hook
Decision - BP-10 (catalog row “Hook/plugin permission veto”, semantics “Programmatic allow/deny/rewrite before the user sees it”): what a pre-tool hook decided about one call.
- Lifecycle
Event - A loop lifecycle moment an embedder may observe (BP-11, catalog
“Lifecycle hooks, config-registered”): the compaction and subagent
boundaries the CLI’s
pre_compact/post_compact/subagent_start/subagent_stophook events are fired from. Observational only — a lifecycle hook can never veto the moment it observes. - Role
- Who authored a
ChatMessage. - Session
Format - An on-disk session format supercode can both read and write.
- Session
Snapshot Reason - Why a watcher emitted a complete session snapshot.
- Session
Source - Which tool produced a session log.
- Session
Watch Event - A normalized event emitted while following a local session.
- Steering
Mode - How queued steering/follow-up messages are drained (S1.7, pi3
steeringMode/followUpMode). - Storage
Locator - Durable storage address for a persisted session.
- Tool
Advertising - How tools are advertised to the model (B6, D16).
- Tool
Outcome - The structural outcome known for a tool-result message.
- Trigger
- Metadata recovered from a session log.
ORCH-3: why a session exists (the trigger noun;
docs/HERMES-IDEAL-SUPPORT-DESIGN.md§3). - Workspace
Kind - Metadata recovered from a session log. ORCH-3 / UNI-9: the typed workspace, derived — never stored.
Constants§
- DEFAULT_
SYSTEM_ PROMPT - A default, deliberately small system prompt. Override it freely.
- SERVED_
MODEL_ KEY - Metadata key carrying the model the PROVIDER said served a response —
distinct from
"model", which every caller sets to the model it REQUESTED. Present only when the response actually reported one. - TOOL_
ERROR_ METADATA_ KEY - Canonical metadata key marking a tool result as a structured error.
- TOOL_
OUTCOME_ UNKNOWN_ METADATA_ KEY - Canonical metadata key marking a tool result whose outcome is unknown.
- UNKNOWN_
MODEL_ CONTEXT_ FLOOR - Conservative fallback context limit for an unrecognized model.
Traits§
- Frontend
Facade Transport - Transport seam consumed by the generated Rust facade client.
- Provider
- Legacy provider abstraction preserved by the composition facade.
Functions§
- core_
messages - Canonical messages participating in cross-format fidelity scoring.
- format_
reply - Format an agent’s final reply for output.
jsonwraps it as{"result": "..."}; otherwise the reply is returned as-is. The stream-json form is the liveAgentEventstream via anEventSink. - is_
tool_ error - Whether a message carries the canonical structured-error marker.
- mark_
tool_ error - Stamp a tool-result message as a structured error.
- mark_
tool_ outcome_ unknown - Stamp a tool-result message as having no structurally known outcome.
- measure_
fidelity - Measure an export/reload cell without applying a regression floor.
- messages_
equal - Compare semantic message fields shared by the supported harnesses.
- messages_
equal_ multimodal - Compare semantics plus multimodal parts and tool names.
- model_
context_ limit - Look up a model’s context-window size by its full provider slug.
- orchestrator_
profile_ dirs - Every profile folder under an orchestrator home, in listing order: the
root (the implicit
defaultprofile) then eachprofiles/<name>/. - project_
root_ for - BP-9 (§3.1
core.project_root_markers, catalog:232 “Project-root detection markers”, cx§6, oc§6): the project root forcwd— the NEAREST ancestor (starting atcwditself) that directly contains any entry named bymarkers.Nonewhen no ancestor carries a marker, or whenmarkersis empty (an empty marker list is an explicit “don’t do root detection”, not an invitation to walk to/). - replay_
eligible - The replayable subsequence of a canonical transcript.
- tool_
outcome - Return the canonical structural outcome for a tool-result message.
Type Aliases§
- Event
Sink - A sink for
AgentEvents. - Lifecycle
Hook - A lifecycle observer: receives every
LifecycleEvent(observational). - Result
- Result alias used throughout the crate.
- Stop
Gate Hook - A stop-gate hook: receives the would-be-final assistant message; returns
Some(reason)to veto termination and continue the loop (the reason is injected as a new user message), orNoneto allow the stop. SeeConfig::stop_gate.